Repository navigation
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.
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.
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.
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.
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).
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.
| 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 |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference