openapi: 3.0.3
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:
    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
    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
    boundary.rect.min_lat:
      name: boundary.rect.min_lat
      in: query
      description: Minimum latitude of rectangular boundary (southern edge)
      schema:
        type: number
        format: float
    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
    boundary.rect.max_lat:
      name: boundary.rect.max_lat
      in: query
      description: Maximum latitude of rectangular boundary (northern edge)
      schema:
        type: number
        format: float
    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
    text:
      name: text
      in: query
      required: true
      description: Free-form text to geocode (addresses, place names, etc.)
      schema:
        type: string
      example: YMCA
    boundary.circle.radius:
      name: boundary.circle.radius
      in: query
      description: Radius in km of the circular boundary
      schema:
        type: number
        format: float
    boundary.circle.lat:
      name: boundary.circle.lat
      in: query
      description: Latitude of the center of a circular boundary
      schema:
        type: number
        format: float
    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.rect.max_lon:
      name: boundary.rect.max_lon
      in: query
      description: Maximum longitude of rectangular boundary (eastern 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
    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
  schemas:
    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: {}
    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
    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
    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
  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