Custom locations
Find points in a location layer by radius, nearest-N, bounding box, key or metadata.
A location is a point in a location layer: a store, a depot, a customer site. Each has a name, an optional Lookup Key and free-form metadata. Find locations by radius, nearest-N, bounding box, Lookup Key or metadata.
Not Geoapify-compatible. /v1/custom/ is our own API. See Custom layers for how to list the layers and Authentication for keys.
Quick start
Find the 2 nearest locations to a point:
curl -s "https://api.data.graphitelab.ai/v1/custom/layers/stores/locations?lat=39.77&lon=-86.16&nearest=2&apiKey=$GRAPHITE_API_KEY"{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"place_id": "gp:layer:stores:86d0a8c5-dcdc-4758-bd8a-f921bbe10984",
"boundary_type": "custom:stores",
"name": "Demo store",
"lookup_key": "store-1",
"metadata": { "region": "central" },
"distance_m": 240.958,
"lon": -86.1581,
"lat": 39.7684,
"datasource": { "sourcename": "The Graphite Lab", "attribution": "© The Graphite Lab", "raw": { "layer": "stores", "revision": 4 } }
},
"geometry": { "type": "Point", "coordinates": [-86.1581, 39.7684] }
}
],
"next_cursor": null
}A location's place_id is gp:layer:<slug>:<uuid>. Show each item's datasource.attribution wherever you display results.
Endpoints
| Operation | Path |
|---|---|
| List or search | GET /v1/custom/layers/{layer}/locations |
| Search with a JSON body | POST /v1/custom/layers/{layer}/locations/search |
{layer} is a slug (^[a-z0-9_]{2,40}$). A zone layer or cell layer answers 404 (Unknown location layer): use zones for those.
Searching
GET .../locations and POST .../locations/search take the same filters, as query parameters or as JSON members. They combine with AND.
| Parameter | Meaning |
|---|---|
lookup_key | Exact match. |
bbox | west,south,east,north. In a JSON body, an array of four numbers. |
meta[key]=value | Metadata contains the member. Repeatable, at most 10. In a JSON body, meta is an object. |
lat + lon with radius | Within radius meters (1 to 500,000), nearest first, paged with next_cursor. |
lat + lon with nearest | The N closest (1 to 1,000), exactly ranked, in one page. next_cursor is always null. max_distance (meters) bounds it. |
limit | 1 to 1,000. Default 100. |
cursor | next_cursor of the previous page. |
lat and lon need radius or nearest. radius and nearest cannot be combined. Radius and nearest results carry distance_m. Without lat and lon, results come in id order.
Full reference: list or search locations
Search with a JSON body
Use POST .../locations/search when the filters are too long for a URL. It is a read: it costs 1 rivet like any other request.
curl -s -X POST "https://api.data.graphitelab.ai/v1/custom/layers/stores/locations/search" \
-H "Authorization: Bearer $GRAPHITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"lat":39.77,"lon":-86.16,"radius":5000,"meta":{"region":"central"}}'The response has the same shape as the list. The body limit is 128 KB.
Full reference: search with a JSON body
Limits
| Limit | Value |
|---|---|
| Search body | 128 KB |
| Page size | 1,000 |
| Radius | 500,000 m |
nearest | 1,000 |
meta[] filters | 10 |
Errors
| Status | When |
|---|---|
| 400 | Bad parameter, lat without lon, lat and lon without radius or nearest, both radius and nearest, bad cursor, bad search body. |
| 401 | Missing or invalid API key. |
| 402 | Your organization is out of rivets (insufficient_rivets) or has no plan (no_plan). |
| 403 | Your organization does not have data API access. |
| 404 | Unknown layer, or a zone or cell layer (Unknown location layer). |
| 413 | Search body over 128 KB. |
| 429 | Over 60 requests per minute. |
| 500, 503 | Unexpected gateway error, or the custom layer store is unavailable or busy. Retry. |
Errors use the error shape.
Try in Playground (signed in to your Graphite Lab organization). Signed out, use the paste-your-key widget on the reference page.