Convert geographic coordinates into places and addresses
openapi: 3.0.3
info:
title: Pelias Geocoding Autocomplete Reverse Geocoding API
description: 'Pelias is a modular, open-source geocoding search engine built on Elasticsearch. It converts addresses and place names into geographic coordinates (forward geocoding) and geographic coordinates into places and addresses (reverse geocoding). Powered entirely by open data from OpenStreetMap, OpenAddresses, Who''s on First, and Geonames, it is freely available under the MIT license and can be self-hosted or accessed via hosted services such as geocode.earth.
'
version: '1.0'
license:
name: MIT
url: https://github.com/pelias/pelias/blob/master/LICENSE
contact:
name: Pelias Team
email: team@pelias.io
url: https://github.com/pelias
x-github-org: https://github.com/pelias
x-documentation: https://github.com/pelias/documentation
servers:
- url: https://api.geocode.earth/v1
description: Geocode.earth hosted Pelias service
- url: http://localhost:3100/v1
description: Self-hosted local Pelias instance
tags:
- name: Reverse Geocoding
description: Convert geographic coordinates into places and addresses
paths:
/reverse:
get:
operationId: reverseGeocode
summary: Reverse geocode coordinates into place/address
description: 'Given a latitude and longitude, returns the nearest places and addresses from all available data sources. Optionally filter by source, layer, or boundary.
'
tags:
- Reverse Geocoding
parameters:
- name: point.lat
in: query
required: true
description: Latitude of the point to reverse geocode (decimal degrees)
schema:
type: number
format: float
minimum: -90
maximum: 90
example: 48.858268
- name: point.lon
in: query
required: true
description: Longitude of the point to reverse geocode (decimal degrees)
schema:
type: number
format: float
minimum: -180
maximum: 180
example: 2.294471
- name: boundary.circle.radius
in: query
description: Radius in km within which to restrict results (max 5)
schema:
type: number
format: float
maximum: 5
example: 1
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/boundary.country'
- $ref: '#/components/parameters/boundary.gid'
- $ref: '#/components/parameters/sources'
- $ref: '#/components/parameters/layers'
responses:
'200':
description: GeoJSON FeatureCollection of reverse geocoding results
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodingResponse'
examples:
eiffel_tower:
$ref: '#/components/examples/EiffelTowerReverse'
'400':
$ref: '#/components/responses/BadRequest'
components:
parameters:
boundary.gid:
name: boundary.gid
in: query
description: Pelias gid of an administrative area to restrict results within
schema:
type: string
example: whosonfirst:locality:101748355
size:
name: size
in: query
description: Maximum number of results to return (default 10, max 40)
schema:
type: integer
minimum: 1
maximum: 40
default: 10
example: 10
sources:
name: sources
in: query
description: 'Comma-separated list of data sources to query. Valid values: openstreetmap (osm), openaddresses (oa), whosonfirst (wof), geonames (gn)
'
schema:
type: string
enum:
- openstreetmap
- osm
- openaddresses
- oa
- whosonfirst
- wof
- geonames
- gn
example: osm
lang:
name: lang
in: query
description: 'BCP47 language tag for preferred response language (e.g. en, fr, de). Not all places have translated names.
'
schema:
type: string
example: en
boundary.country:
name: boundary.country
in: query
description: 'Comma-separated list of ISO-3166 alpha-2 or alpha-3 country codes to restrict results
'
schema:
type: string
example: GBR
layers:
name: layers
in: query
description: 'Comma-separated list of layer types to restrict results. Valid values: venue, address, street, neighbourhood, borough, localadmin, locality, county, macrocounty, region, macroregion, country, coarse, postalcode
'
schema:
type: string
example: address,locality
schemas:
GeocodingResponse:
type: object
description: GeoJSON FeatureCollection returned by all Pelias endpoints
required:
- geocoding
- type
- features
properties:
geocoding:
$ref: '#/components/schemas/GeocodingMetadata'
type:
type: string
enum:
- FeatureCollection
description: GeoJSON type identifier
features:
type: array
description: List of matched place features
items:
$ref: '#/components/schemas/GeocodingFeature'
bbox:
type: array
description: Bounding box of all results [minLon, minLat, maxLon, maxLat]
items:
type: number
minItems: 4
maxItems: 4
ErrorResponse:
type: object
description: Error response from the Pelias API
properties:
geocoding:
type: object
properties:
errors:
type: array
items:
type: string
example:
- '''text'' parameter is required'
query:
type: object
additionalProperties: true
type:
type: string
enum:
- FeatureCollection
features:
type: array
items: {}
GeocodingMetadata:
type: object
description: Metadata about the geocoding request and response
properties:
version:
type: string
description: Pelias API version
example: '1.0'
attribution:
type: string
description: Attribution URL for the geocoding service
example: https://geocode.earth/guidelines
query:
type: object
description: Parsed query parameters
additionalProperties: true
engine:
type: object
description: Engine version information
properties:
name:
type: string
example: Pelias
author:
type: string
example: Mapzen
version:
type: string
example: '1.0'
timestamp:
type: integer
description: Unix timestamp of the response (milliseconds)
example: 1525718151924
GeocodingFeature:
type: object
description: A GeoJSON Feature representing a geocoded place
required:
- type
- geometry
- properties
properties:
type:
type: string
enum:
- Feature
geometry:
type: object
description: GeoJSON Point geometry (coordinates are [longitude, latitude])
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Point
coordinates:
type: array
description: '[longitude, latitude] in decimal degrees'
items:
type: number
minItems: 2
maxItems: 2
properties:
$ref: '#/components/schemas/PlaceProperties'
bbox:
type: array
description: Feature-level bounding box [minLon, minLat, maxLon, maxLat]
items:
type: number
minItems: 4
maxItems: 4
PlaceProperties:
type: object
description: Properties of a geocoded place
properties:
id:
type: string
description: Source-specific record ID
example: '101750367'
gid:
type: string
description: Pelias Global Identifier (source:layer:id)
example: whosonfirst:locality:101750367
layer:
type: string
description: Data layer/type (venue, address, locality, country, etc.)
example: locality
source:
type: string
description: Data source name
example: whosonfirst
source_id:
type: string
description: ID within the original source dataset
example: '101750367'
name:
type: string
description: Short place name (business name, street address, locality, etc.)
example: London
label:
type: string
description: Human-friendly full label ready for display
example: London, England, United Kingdom
confidence:
type: number
format: float
minimum: 0
maximum: 1
description: Confidence score for this result (0–1)
example: 0.949
distance:
type: number
format: float
description: Distance in km from query point (reverse geocoding only)
country:
type: string
example: United Kingdom
country_gid:
type: string
example: whosonfirst:country:85633159
country_a:
type: string
description: ISO-3166 alpha-3 country code
example: GBR
macroregion:
type: string
example: England
macroregion_gid:
type: string
example: whosonfirst:macroregion:404227469
region:
type: string
example: City of Westminster
region_gid:
type: string
example: whosonfirst:region:85684061
region_a:
type: string
description: Region abbreviation
example: CA
county:
type: string
example: Maui
county_gid:
type: string
localadmin:
type: string
localadmin_gid:
type: string
locality:
type: string
example: London
locality_gid:
type: string
example: whosonfirst:locality:101750367
borough:
type: string
example: Manhattan
borough_gid:
type: string
neighbourhood:
type: string
example: Notting Hill
neighbourhood_gid:
type: string
postalcode:
type: string
example: '10001'
housenumber:
type: string
example: '30'
street:
type: string
example: West 26th Street
categories:
type: array
description: Place categories (returned when categories parameter is present on /place)
items:
type: string
example:
- entertainment
addendum:
type: object
description: Additional source-specific metadata
additionalProperties: true
examples:
EiffelTowerReverse:
summary: Reverse geocode the Eiffel Tower coordinates
value:
geocoding:
version: '1.0'
attribution: https://geocode.earth/guidelines
query:
point.lat: 48.858268
point.lon: 2.294471
size: 10
timestamp: 1525718151924
type: FeatureCollection
features:
- type: Feature
geometry:
type: Point
coordinates:
- 2.294471
- 48.858268
properties:
id: way/5013364
gid: openstreetmap:venue:way/5013364
layer: venue
source: openstreetmap
name: Tour Eiffel
confidence: 0.9
distance: 0.001
country: France
country_a: FRA
locality: Paris
label: Tour Eiffel, Paris, France
responses:
BadRequest:
description: Bad request — missing or invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
geocoding:
errors:
- '''text'' parameter is required'
type: FeatureCollection
features: []
externalDocs:
description: Pelias Documentation
url: https://github.com/pelias/documentation