Appearance
search_url tag (JSON endpoint)
Search the locations as JSON or GeoJSON, for a headless site, an app or your own Javascript. The search_url tag gives the URL of the endpoint; a visitor (or your frontend) adds the searched location to it. (from v4.0.0)
{exp:reinos_maps_locator:search_url channel="stores" origin="https://www.example.com"}The params of the tag are signed in the URL: a visitor can't change the channels, the status or the limits, only the location, radius, categories and the page. The signature stays valid as long as the encryption key of the site doesn't change, so a headless site can copy the URL once into its config. Change a param and you need a new URL.
Parameters
channel
The channel(s) to search, separated by a pipe. Required.
channel="stores|dealers"status
The status of the entries, separated by a pipe. Default open.
status="open" [OPTIONAL]limit
The maximum number of locations per response, at most 100. A request can ask for fewer with &limit=. Default 20.
limit="20" [OPTIONAL]radius
The radius when a request has no radius. Default 25.
radius="25" [OPTIONAL]max_radius
The largest radius a request can search. Default 100, 0 for no maximum.
max_radius="100" [OPTIONAL]metric
km or mile (also mi). Default km.
metric="km" [OPTIONAL]category_match
any: a location in one of the requested categories, all: in all of them. Default any.
category_match="any" [OPTIONAL]nearest
The number of nearest locations when a search has no results within the radius, 0 to turn it off. Default 5.
nearest="5" [OPTIONAL]sticky_first
With yes the locations of sticky entries come first. Default no.
sticky_first="no" [OPTIONAL]origin
The site(s) that call the endpoint from the browser, separated by a pipe. Only these get the CORS header Access-Control-Allow-Origin. Not needed on the same domain or for server-side requests.
origin="https://www.example.com|https://app.example.com" [OPTIONAL]format
geojson to add &format=geojson to the URL. A request can also add it itself. Default JSON.
format="geojson" [OPTIONAL]Request
Add the search to the URL with a GET request:
| Param | |
|---|---|
location | A place, postal code or address (utrecht), or a coordinate (52.09,5.12) |
lat, lng | A coordinate, e.g. from use my location. No geocoding request is made |
radius | The radius, decimals allowed, at most max_radius |
categories | Category ids, names or url titles: categories[]=3&categories[]=4 or categories=3|4 |
offset | Skip this number of locations, for paging |
limit | Fewer locations than the limit of the tag |
format | json (default) or geojson |
Without location or lat/lng the response has all locations (sorted by title), e.g. to fill a map before a search.
https://www.example.com/?ACT=12&config=...&signature=...&location=utrecht&radius=25&categories[]=3Response
json
{
"status": "ok",
"search": {
"location": "utrecht",
"lat": 52.0907,
"lng": 5.1214,
"radius": 25,
"unit": "km",
"categories": ["3"]
},
"total": 12,
"count": 10,
"offset": 0,
"limit": 10,
"has_more": true,
"locations": [
{
"id": 5,
"entry_id": 42,
"channel_id": 3,
"title": "Store Utrecht",
"url_title": "store-utrecht",
"address": "Oudegracht 1, 3511 AA Utrecht, Netherlands",
"street_name": "Oudegracht",
"street_number": "1",
"postal_code": "3511 AA",
"city": "Utrecht",
"country": "Netherlands",
"country_code": "NL",
"directions_url": "https://www.google.com/maps/dir/?api=1&destination=52.0907,5.1214",
"location_key": "location_5",
"sticky": false,
"lat": 52.0907,
"lng": 5.1214,
"distance": 0.4,
"distance_unit": "km"
}
]
}search is null without a searched location. status is one of:
| Status | |
|---|---|
ok | The locations within the radius (or all locations without a search) |
nearest | Nothing within the radius, these are the nearest locations (see nearest) |
no_results | Nothing within the radius and nearest="0" |
not_found | The location could not be geocoded |
With format=geojson the response is a FeatureCollection: every location is a Feature with a Point and the fields above as properties. status, search, total and the paging fields are on the FeatureCollection itself.
Errors
| HTTP | status | |
|---|---|---|
403 | invalid_signature | The URL was changed or the encryption key of the site changed, use a new URL from the tag |
429 | rate_limited | Too many requests, try again after the Retry-After header (60 seconds) |
Limits
A search on a place or address is a geocoding request and counts for the Searches per minute setting. A search on a coordinate, or without a location, only queries your own index and has a higher limit (120 per minute per visitor). A response can be cached for a minute (Cache-Control: public, max-age=60); the geocoder caches the places itself.
The fields of the entry (custom fields) are not in the response: get them with the entry_id from your own template or the EE API, or render the list on the server with the locator tag.