Locations
Retrieve Locations
Retrieve detailed information about a specific location. This endpoint provides comprehensive location data.
URL Parameters
location_id
(required): The unique identifier of the location, prefixed withloc_
List Locations
Retrieve a list of locations with comprehensive filtering, searching, and pagination capabilities. Two endpoint variations are available:
Standard List Endpoint
Provides detailed location information with pagination support.
Cached List Endpoint
Optimized for quick access to basic location data without pagination.
Query Parameters
Filtering
The API supports comprehensive filtering of locations through query parameters. Multiple filters can be combined to refine your results.
Filtering Examples
- Filter by
group_id
orgroup
- Filter by
user_id
oruser
- Filter by metadata
Pagination
The response includes a pagination object with the following properties:
- has_more - Indicates if there are more locations available
- page - Current page number (default: 1)
- limit - Number of results per page (default: 25)
- total_count - Total number of locations in the database.
To retrieve the next page of results:
Sorting
Control the order of results using:
If no sorting parameter is specified, the system defaults to sorting by created_at
in ascending order asc
Example with sorting:
Search
The API provides advanced full-text search capabilities through the search parameter, allowing you to search locations using fuzzy, typo-tolerant matching across multiple fields. The search functionality examines key location properties including:
group_names
name
code
metadata
Each location in the search results includes a special _search
object that provides detailed information about the match:
The _search
object includes highlighted matches using <mark>
tags, making it easy to emphasize matching text in user interfaces. It also provides a relevance score between 0 and 1, where higher values indicate better matches.
By default, search results are ordered by relevance score to show the best matches first. However, you can override this by specifying an order_by parameter to sort by other fields like created_at
, updated_at
, name
, code
. The search functionality can be combined with other filter parameters to refine your results further.