Outdoor places in an area
GET https://api.trailsplits.com/pois/v1/bbox
Checked by a live probe Key optional · 500 credits a day without one 1 credit per call Daily area ceiling: 3,000 on Free
Huts, shelters and places to stay, places to eat, drinking water and springs, passes, parking, villages and transport stops in a small box, as flat records (lat, lon, ele and OSM tags as mapped), not GeoJSON Features. Viewpoints and peaks are not here: they are in search and the map tiles. Each side of the box may be at most 2°. artifact_version names the weekly release used.
Example
# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/pois/v1/bbox?min_lat=46&min_lon=7.7&max_lat=46.05&max_lon=7.8&kind=hut&limit=5' \
-H "Authorization: Bearer $TRAILSPLITS_API_KEY" Parameters
| Name | In | Description |
|---|---|---|
min_latrequired | query | South. |
min_lonrequired | query | West. |
max_latrequired | query | North. |
max_lonrequired | query | East. |
kind | query | Comma-separated kinds, for example hut,shelter,water. An unknown kind matches nothing (no error). Without it, every kind. |
limit | query | Records. |
Response
| Field | Type | Description |
|---|---|---|
type | string: FeatureCollection | |
count | integer | |
artifact_version | string | |
features | array |
Full response schema (JSON Schema)
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"FeatureCollection"
]
},
"count": {
"type": "integer"
},
"artifact_version": {
"type": "string"
},
"features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"name": {
"type": "string",
"nullable": true
},
"ele": {
"type": "number",
"nullable": true
},
"lat": {
"type": "number"
},
"lon": {
"type": "number"
},
"osm_id": {
"type": "string",
"nullable": true
},
"tags": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"kind",
"lat",
"lon"
]
}
}
},
"required": [
"type",
"features"
]
}Errors
400, plus the gateway's 401, 429 and 503 (every error code). A refused request costs no credits.
Contract
-
First-party consumers:
- the site's POI layer, huts layer, nearest overnight and access points;
Operations
Both are GET, answer application/json and send CORS (Access-Control-Allow-Origin: *).
1. Places in a box
GET /pois/v1/bbox?min_lat=S&min_lon=W&max_lat=N&max_lon=E[&kind=k1,k2][&limit=1..10000]
| Parameter | |
|---|---|
min_lat, min_lon, max_lat, max_lon | Required, WGS84 degrees. At most 2° a side |
kind | Optional, comma-separated kinds from the table below. An unknown kind matches nothing (no error) |
limit | Default 2,000, at most 10,000 (a larger value is cut to 10,000, a non-number reads as 2,000) |
{ "type": "FeatureCollection", "count": 2, "artifact_version": "osm_weekly_20261004_0202",
"features": [ { "kind": "water", "name": null, "ele": null, "lat": 46.007358, "lon": 7.74199,
"osm_id": "n1458721469", "wikidata": null, "entrance": null, "tags": { "amenity": "drinking_water" } } ] }
features are flat records, not GeoJSON Features, despite the type (kept for the first consumers). There is no geometry and no properties: read lat and lon.
Order: none promised. Rows come in the spatial index's order. A box holding more than limit matching rows returns some of them, with no flag saying more exist. A caller that needs all of them asks with a kind filter or a smaller box, and takes count == limit as "maybe more".
2. Current facts for stored ids
GET /pois/v1/by-id?ids=n123,w456,r789
There are 1–200 ids, each n, w or r followed by the OSM id. The answer is { artifact_version, count, places: { "<id>": record | null } }. Null means the id is not in the served release (deleted, retagged out of every kind, or renamed into another id). It lets a saved trip or watch check that a stored stay or stop still exists.
Record
| Field | Meaning |
|---|---|
kind | One of the kinds below |
name | OSM name, or null |
ele | Metres as tagged (ele, ele:msl, altitude; a unit suffix read), or null. Never derived |
lat, lon | WGS84, 6 decimals. A way or relation is placed at its centroid. |
osm_id | n…, w…, r…, or x:<id> for a place added from an official source that OSM does not hold yet (add_place; its source in tags["trailsplits:source"]; when OSM maps it, the OSM record replaces it) |
wikidata | Q… or null |
entrance | For a place mapped as a way or relation: {lat, lon, source}. source is entrance=<value> for a mapped entrance node (main first), or centroid where none is mapped. Null for nodes |
tags | OSM tags as mapped, the kept set per kind (below). Never interpreted: seasonal, opening_hours, drinking_water and the rest are the mapper's words |
Kinds and kept tags
| Group | Kinds | Tags kept |
|---|---|---|
| Accommodation | hut (alpine and wilderness huts), shelter, guest_house, hostel, hotel, camp_site, chalet | name and name:*, alt and official names, operator, website, phone, email (contact:* folded in), opening_hours, seasonal, reservation, capacity, beds, fee, winter_room, shelter_type, drinking_water, access, dog, ref, ele, wikidata, wikipedia, tourism, amenity, cuisine |
| Meals | restaurant, cafe, pub | as accommodation. A restaurant or cafe with no ele is kept only within reach of a hiking way and then carries near_hiking_way: "yes" |
| Transport | station, halt (rail platforms no bus serves), tram_stop, bus_stop, cable_car (lift stations), ferry_terminal (boat landings, however tagged) | name and name:*, ref, network, operator, public_transport, railway, station, aerialway, ele, wikidata, amenity and the mode tags (ferry, bus, tram, train, light_rail, subway, funicular) |
| Water | water (drinking water and fountains), spring | name, ele, wikidata, place, natural, mountain_pass, amenity, seasonal, intermittent, drinking_water, access, opening_hours, fountain, operator, check_date, check_date:drinking_water |
| Other | parking, pass (passes and saddles), village, town, hamlet | name, ele, wikidata, place, natural, mountain_pass, amenity |
Kinds are additive. A new kind may appear in a weekly build (announced in the release notes and declared to the release gate), so a client ignores the kinds it does not know.
Sources and licence
Every record comes from OpenStreetMap, © OpenStreetMap contributors, ODbL 1.0. A product that shows the records shows the OSM attribution. The x: records come from the official sources named in their tags (source and credit fields), under those sources' terms.
Freshness: the weekly planet build (Sunday, from that day's planet), promoted after the release gate. artifact_version names the release served.
Errors
The origin answers 400 with {"error": "<message>"}, a plain message rather than the api-errors/1 object (a known gap, see below):
| Status | When | ||
|---|---|---|---|
| 400 | Missing or unreadable box (Required: min_lat, min_lon, max_lat, max_lon); a side over 2° (Bounding box too large (max 2° per side)); ids missing, over 200, or not `n | w | r` + digits |
| 503 | {"error": "places_unavailable", "detail"} with Retry-After: 1: the places database failed to answer this request. Retry; never read it as "nothing here" (since 6 Oct 2026; before, such a failure answered an empty 200) | ||
| 401, 402, 429, 503 | From the gateway, in api-errors/1 form (keys, credits, rate, shedding): api-errors-v1.md |
200 with no records means the box holds none, or the release has no places database at all (the gate and the watchdog catch that before a release is served). by-id answers null for an id only when the read succeeded and the id is not there.
Versioning
Additive changes (a field, a kind, a kept tag) keep places/1 and are announced in the release notes. Removing or renaming a field or kind, or changing a record's meaning, is places/2, with both served side by side for the deprecation window in api-gateway-v1.md.