Resources API Querying and Search
Retrieving Multiple Resources (pagination, sorting and filtering)
When retrieving multiple resources using the plural endpoint (e.g., GET /resources/{plural resource name}), you can use pagination, sorting, and filtering to manage the results.
Pagination and Sorting
When retrieving multiple resources using the plural endpoint (e.g., GET /resources/{plural resource name}), the following query parameters are supported for pagination and sorting:
| Parameter | Description | Type | Required | Example |
|---|---|---|---|---|
limit | Maximum number of results to return (1-500) | integer | No | 10 |
offset | Number of results to skip for pagination | integer | No | 0 |
sort_by | Field name to sort results by | string | No | name |
sort_order | Sort direction | string | No | asc or desc |
Example
curl -X GET "https://api0.spaaza.com/resources/{plural resource name}?limit=25&offset=50&sort_by=name&sort_order=asc" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}" \
-H "X-Spaaza-Response-Recursion-Level: 3"
Filtering Multiple Resources
For plural resource endpoints, you can filter results using multiple properties that have the filter-property attribute set to true. These filterable properties are identified in each resource's documentation in the "Spaaza Vendor Attributes" column of the Properties table.
You can combine filter properties with pagination and sorting parameters:
curl -X GET "https://api0.spaaza.com/resources/{plural resource name}?{filter_property}={value}&{filter_property}={value}&limit=10" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}" \
-H "X-Spaaza-Response-Recursion-Level: 3"
Refer to each resource's Properties table to see which properties support filtering.
Text Search
Some resources support text search on specific properties, enabling partial matching and prefix-based filtering. This is useful when you need to find resources where a property contains a particular term rather than matching an exact value.
Identifying Text Search Properties
Properties that support text search are marked with fulltext-search: true in the "Spaaza Vendor Attributes" column of each resource's Properties table. You can also retrieve this information programmatically from the Schema Endpoint by looking for the x-spaaza-fulltext-search attribute.
Search Syntax
Text search uses the OpenAPI 3.0 "deepObject" query parameter style:
?search[{property_name}]={search_term}
For example, to filter businesses by name containing "shop":
?search[name]=shop
You can also use * as the property name to apply the search term across all text-search-enabled properties for that resource:
?search[*]={search_term}
For example, to filter businesses where either name or owner_code contains "amsterdam":
?search[*]=amsterdam
Search Behaviour
Text search supports partial matching with prefix search. For example, searching for "shop" will match "Shop A", "Coffee Shop", "Shopify Store", etc. Multiple search terms can be separated by spaces or commas within a single search value.
Only one search key can be used per request. You can either target a specific property (e.g., search[name]=term) or use search[*]=term to apply the search across all text-search-enabled properties. If you need to filter by additional criteria, combine text search with equality filters (see below).
The match_all Parameter
When providing multiple search terms (separated by spaces or commas), you can control how they are matched:
| Parameter | Type | Default | Description |
|---|---|---|---|
match_all | boolean | false | When true, all search terms must be present in the match. When false, any matching term qualifies the result. |
Combining Text Search with Filters
Text search can be combined with standard equality filters. For example, to search for businesses with "central" in the name that are not shut down:
curl -X GET "https://api0.spaaza.com/resources/businesses?search[name]=central&is_shut_down=false&limit=10" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
Example: Text Search on Business Resource
The Business resource supports text search on the name and owner_code properties:
# Search for businesses with "amsterdam" in the name
curl -X GET "https://api0.spaaza.com/resources/businesses?search[name]=amsterdam" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
# Search for businesses with "store" in the owner code, requiring all terms to match
curl -X GET "https://api0.spaaza.com/resources/businesses?search[owner_code]=store&match_all=true" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
# Search for businesses where either name or owner_code contains "central"
curl -X GET "https://api0.spaaza.com/resources/businesses?search[*]=central" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
Location Search
Some resources support geospatial filtering based on latitude and longitude coordinates. This enables finding resources within a specified radius of a given location, with results ordered by distance from the search point.
Identifying Location Search Support
Resources that support location search have latitude and longitude properties in their schema. Currently, the Business resource supports location search.
Location Search Syntax
Location search uses the OpenAPI 3.0 "deepObject" query parameter style:
?location[latitude]={latitude}&location[longitude]={longitude}&location[radius_km]={radius}
| Parameter | Description | Type | Required | Default |
|---|---|---|---|---|
location[latitude] | Latitude of the search point in decimal degrees (-90 to 90) | float | Yes | - |
location[longitude] | Longitude of the search point in decimal degrees (-180 to 180) | float | Yes | - |
location[radius_km] | Maximum distance in kilometres from the search point | float | No | 25 |
Location Search Behaviour
When location search parameters are provided, the API filters results to only include resources within the specified radius and orders results by distance from the search point (closest first). This distance-based ordering takes precedence over any sort_by parameter.
Resources that match the location criteria will include a distance field in their response (e.g., business_distance_km for the Business resource) showing the calculated distance in kilometres from the search coordinates.
Both latitude and longitude must be provided together. If only one coordinate is supplied, the API will return a parameter_invalid error. Resources without stored coordinates are excluded from location search results.
Combining Location Search with Other Filters
Location search can be combined with text search and equality filters. When combined, all criteria must be satisfied for a resource to be included in the results. Results are still ordered by distance when location search is active.
# Find businesses with "central" in the name within 10km of Amsterdam
curl -X GET "https://api0.spaaza.com/resources/businesses?search[name]=central&location[latitude]=52.3676&location[longitude]=4.9041&location[radius_km]=10" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
Example: Location Search on Business Resource
# Find businesses within 25km (default radius) of a location
curl -X GET "https://api0.spaaza.com/resources/businesses?location[latitude]=52.3676&location[longitude]=4.9041" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"
# Find businesses within 50km of a location
curl -X GET "https://api0.spaaza.com/resources/businesses?location[latitude]=52.3676&location[longitude]=4.9041&location[radius_km]=50" \
-H "X-Spaaza-Chain-ID: {chain_id}" \
-H "X-Spaaza-API-version: 1.6.1" \
-H "X-Spaaza-Session-User-ID: {your user ID}" \
-H "X-Spaaza-Session-Key: {your key}"