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