Skip to content

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

Outdoor places in an area (curl)
# 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"

Sends a real request, with your key or the keyless allowance.

Parameters

NameInDescription
min_latrequiredquerySouth.
min_lonrequiredqueryWest.
max_latrequiredqueryNorth.
max_lonrequiredqueryEast.
kindqueryComma-separated kinds, for example hut,shelter,water. An unknown kind matches nothing (no error). Without it, every kind.
limitqueryRecords.

Response

FieldTypeDescription
typestring: FeatureCollection
countinteger
artifact_versionstring
featuresarray
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_lonRequired, WGS84 degrees. At most 2° a side
kindOptional, comma-separated kinds from the table below. An unknown kind matches nothing (no error)
limitDefault 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

FieldMeaning
kindOne of the kinds below
nameOSM name, or null
eleMetres as tagged (ele, ele:msl, altitude; a unit suffix read), or null. Never derived
lat, lonWGS84, 6 decimals. A way or relation is placed at its centroid.
osm_idn…, 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)
wikidataQ… or null
entranceFor 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
tagsOSM 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

GroupKindsTags kept
Accommodationhut (alpine and wilderness huts), shelter, guest_house, hostel, hotel, camp_site, chaletname 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
Mealsrestaurant, cafe, pubas accommodation. A restaurant or cafe with no ele is kept only within reach of a hiking way and then carries near_hiking_way: "yes"
Transportstation, 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)
Waterwater (drinking water and fountains), springname, ele, wikidata, place, natural, mountain_pass, amenity, seasonal, intermittent, drinking_water, access, opening_hours, fountain, operator, check_date, check_date:drinking_water
Otherparking, pass (passes and saddles), village, town, hamletname, 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):

StatusWhen
400Missing 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 `nwr` + 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, 503From 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.