Real-time type-ahead geocoding for user input
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pelias:pelias-autocomplete-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Pelias Geocoding Autocomplete 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: Autocomplete
description: Real-time type-ahead geocoding for user input
paths:
/autocomplete:
get:
operationId: autocomplete
summary: Type-ahead autocomplete geocoding
description: Returns real-time geocoding suggestions as the user types. Best used with client-side throttling (5–10 requests per second). Results include GeoJSON features ranked by relevance and optional geographic focus.
tags:
- Autocomplete
parameters:
- $ref: '#/components/parameters/text'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/focus.point.lat'
- $ref: '#/components/parameters/focus.point.lon'
- $ref: '#/components/parameters/boundary.rect.min_lon'
- $ref: '#/components/parameters/boundary.rect.max_lon'
- $ref: '#/components/parameters/boundary.rect.min_lat'
- $ref: '#/components/parameters/boundary.rect.max_lat'
- $ref: '#/components/parameters/boundary.circle.lat'
- $ref: '#/components/parameters/boundary.circle.lon'
- $ref: '#/components/parameters/boundary.circle.radius'
- $ref: '#/components/parameters/boundary.country'
- $ref: '#/components/parameters/boundary.gid'
- $ref: '#/components/parameters/sources'
- $ref: '#/components/parameters/layers'
responses:
'200':
description: GeoJSON FeatureCollection of autocomplete suggestions
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodingResponse'
'400':
$ref: '#/components/responses/BadRequest'
components:
parameters:
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
boundary.circle.lat:
name: boundary.circle.lat
in: query
description: Latitude of the center of a circular boundary
schema:
type: number
format: float
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
boundary.circle.radius:
name: boundary.circle.radius
in: query
description: Radius in km of the circular boundary
schema:
type: number
format: float
boundary.rect.max_lat:
name: boundary.rect.max_lat
in: query
description: Maximum latitude of rectangular boundary (northern edge)
schema:
type: number
format: float
boundary.circle.lon:
name: boundary.circle.lon
in: query
description: Longitude of the center of a circular boundary
schema:
type: number
format: float
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
text:
name: text
in: query
required: true
description: Free-form text to geocode (addresses, place names, etc.)
schema:
type: string
example: YMCA
boundary.rect.min_lon:
name: boundary.rect.min_lon
in: query
description: Minimum longitude of rectangular boundary (western edge)
schema:
type: number
format: float
focus.point.lat:
name: focus.point.lat
in: query
description: Latitude of the focus point to boost nearby results
schema:
type: number
format: float
minimum: -90
maximum: 90
example: 37.7749
boundary.rect.min_lat:
name: boundary.rect.min_lat
in: query
description: Minimum latitude of rectangular boundary (southern edge)
schema:
type: number
format: float
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
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
focus.point.lon:
name: focus.point.lon
in: query
description: Longitude of the focus point to boost nearby results
schema:
type: number
format: float
minimum: -180
maximum: 180
example: -122.4194
boundary.rect.max_lon:
name: boundary.rect.max_lon
in: query
description: Maximum longitude of rectangular boundary (eastern edge)
schema:
type: number
format: float
schemas:
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
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
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: {}
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