Pelias Geocoder — OpenAPI 3.1

A full OpenAPI 3.1 description of the Pelias geocoder HTTP API (v1, matching pelias/api 7.x). The spec is hand-written from the upstream route handlers, sanitizers, and pelias/documentation — not auto-derived, so every parameter, enum, and schema reflects real server behaviour.

Layout

openapi/
├── openapi.yaml          # the spec (single file, self-contained)
├── examples/             # realistic request / response JSON pairs
│   ├── search.response.json
│   ├── autocomplete.response.json
│   └── reverse.response.json
├── package.json          # redocly devDependency + scripts
└── .gitignore

Validate

npx --yes @redocly/cli@latest lint openapi.yaml
# or, after `npm install`:
npm run lint

Preview

Interactive ReDoc preview with hot reload:

npm run preview
# open http://127.0.0.1:8080

Static HTML build:

npm run build          # writes dist/index.html
npm run bundle         # writes dist/openapi.bundled.yaml

Generate clients

With openapi-generator-cli:

# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./clients/ts

# Python
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./clients/python \
  --additional-properties=packageName=pelias_client

What's covered

• GET /search, POST /search
• GET /search/structured
• GET /autocomplete
• GET /reverse
• GET /nearby
• GET /place
• GET /status
• GET /attribution
• Every documented query parameter (text, focus.point.*, boundary.rect.*, boundary.circle.*, boundary.country, boundary.gid, sources, layers, categories, lang, size, plus the eight structured fields).
• Full GeoJSON FeatureCollection / Feature / Point schemas, the Pelias geocoding envelope, and the full properties hierarchy (country → neighbourhood, match_type, accuracy, confidence, distance, addendum).
• Enums for layers, sources, match_type, accuracy.

What's NOT covered

• Authentication. The reference pelias/api ships with no auth. Hosted providers (Geocode Earth etc.) layer their own API-key schemes on top — the spec declares both api_key query and Authorization header security schemes, but the details vary per provider.
• Admin / debug routes (/v1/debug, _search, internal /config). Not part of the public surface.
• Per-provider rate-limit headers (e.g. X-RateLimit-Remaining). Not emitted by the reference server.
• Deprecated quattroshapes source. Replaced by whosonfirst in 2016.

Contributing

This spec is intended to be upstream-able to pelias/documentation. PRs welcome — keep parameter names, defaults, and caps in sync with pelias/api's sanitizer/ directory.