Skip to content

Spec Endpoints Places

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Endpoints, Places

Part of the Technical Specification. Requirement prefix: FR-PLACE. Shared inputs, types and rules: Spec: Resource Model. Envelope: Spec: Common Envelope. Scope for all operations here: places.

Places resolve first for every other feature. All examples show data only, with placeholder values; meta and links follow the envelope.

1. Search places

GET /v1/places · operationId searchPlaces · MCP counterpart: place search

Purpose. Find towns, districts, localities and other named places by text, optionally near a point.

Parameter Type Required Default Bounds Meaning
q string yes 1–120 characters Search text; diacritics and case are ignored (Koln finds Köln)
near lat,lon no Bias towards results near this point
kind list of enum municipality, district, locality, region, state, station_area, other no all Restrict kinds
state ISO 3166-2 no DE-xx Restrict to a federal state
limit, cursor, fields, lang no 10 1–50 Paging, envelope rules

Order. Relevance descending, then distance to near ascending when given, then id.

{
  "data": [
    {
      "id": "pl_7kQ2",
      "name": "Köln",
      "kind": "municipality",
      "region": {"state": "DE-NW", "stateName": "Nordrhein-Westfalen", "district": "Köln", "municipality": "Köln"},
      "location": {"lat": 50.937531, "lon": 6.960279},
      "bbox": [6.772531, 50.830449, 7.162028, 51.084974],
      "matchedOn": "name",
      "sourceFamily": "places.gazetteer"
    }
  ]
}
Field Meaning
kind Open enum (ENV-050)
location A representative point of the place, not necessarily its centroid; the same point every operation uses for this place
bbox [min_lon, min_lat, max_lon, max_lat], nullable
matchedOn name, alternate_name, postcode

Errors: 400 invalid-parameter. An empty result is 200 with data: [], never 404.

2. Get a place

GET /v1/places/{placeId} · operationId getPlace

Returns one place in the shape above. No statistics (population or similar) are served. 404 not-found for an unknown or retired id; a retired id that has a successor answers 308 to it.

3. Describe a point

GET /v1/locations/describe?at=lat,lon · operationId describeLocation · MCP counterpart: describe a location

Purpose. Answer "where is this?": the place, region and nearest motorway junction for a coordinate.

{
  "data": {
    "point": {"lat": 48.400101, "lon": 9.987632},
    "place": {"id": "pl_9xT1", "name": "Ulm", "kind": "municipality"},
    "region": {"state": "DE-BW", "stateName": "Baden-Württemberg", "district": "Ulm", "municipality": "Ulm"},
    "nearestAddress": {"street": "Example Street", "houseNumber": "1", "postcode": "89073", "locality": "Ulm", "distanceM": 35},
    "nearestJunction": {"id": "jn_A8_61", "road": "A8", "name": "Ulm-West", "number": "61", "distanceM": 3200}
  }
}

nearestAddress and nearestJunction are null when none lies within places.describe_max_distance_m. Errors: 400, 422 outside-coverage.

4. Search addresses

GET /v1/addresses · operationId searchAddresses · MCP counterpart: address search

Parameter Type Required Default Meaning
q string, 3–160 characters yes Street and house number, optionally postcode and locality
near, state, limit (default 10, max 50), cursor, fields, lang no As in place search

Item: id (ad_…), address (Address), location, matchQuality (exact, street, locality), sourceFamily. Addresses from share-alike sources carry the share-alike flag in attribution (LIC-005).

5. Points of interest

GET /v1/points-of-interest · operationId listPointsOfInterest · MCP counterpart: point-of-interest search

Parameter Type Required Default Meaning
location (at, place or q) yes FR-LOC-001
radius_m integer no 2 000 Up to geo.max_radius_m
category list of open enum (hospital, pharmacy, police, rest_area, workshop, supermarket, toilet, …) yes Categories
name string no Name contains
limit, cursor, fields, geometry, lang no 20

Order: distance ascending, then id. Item: id (poi_…), name, category, location, distanceM, address (nullable), openingHours (the source's opening-hours string, nullable, not interpreted), sourceFamily.

Requirements

ID Requirement Verification
FR-PLACE-001 Place search MUST be insensitive to case and diacritics and MUST match alternate names and postcodes. Unit
FR-PLACE-002 Place search MUST return 200 with an empty list when nothing matches; only operations that need a single resolved place use 404 or 422 (FR-LOC-002). Handler
FR-PLACE-003 Every place MUST carry a single representative point, and every operation that resolves that place MUST use that same point, so that two spellings of one place give identical answers. Parity
FR-PLACE-004 GET /v1/places/{placeId} MUST resolve every place id any operation has returned within the id's lifetime; a retired id with a successor MUST redirect with 308. Handler
FR-PLACE-005 Describe a point MUST return the place, the region down to municipality, and the nearest address and motorway junction within configured distances, or null for each. Handler
FR-PLACE-006 Address search MUST normalise house numbers (case, spaces) and recognise a five-digit postcode anywhere in the text. Unit
FR-PLACE-007 Points of interest MUST require at least one category and MUST order by distance then id. Handler
FR-PLACE-008 No place payload MUST contain population or other statistics. Review

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally