openapi: 3.0.3
info:
  title: Pelias Geocoding Autocomplete Forward 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: Forward Geocoding
  description: Convert text or addresses into geographic coordinates
paths:
  /search:
    get:
      operationId: searchGeocode
      summary: Forward geocode a free-form text query
      description: 'Search for places by free-form text. Returns up to 10 GeoJSON features by default. Supports filtering by data source, layer, bounding box, circle, and country.

        '
      tags:
      - Forward Geocoding
      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 geocoding results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingResponse'
              examples:
                ymca_search:
                  $ref: '#/components/examples/YMCASearch'
        '400':
          $ref: '#/components/responses/BadRequest'
  /search/structured:
    get:
      operationId: structuredGeocode
      summary: Forward geocode using structured address components
      description: 'Search for places by providing individual address components (address, neighbourhood, borough, locality, county, region, postalcode, country). Reduces ambiguity compared to free-form text search. Currently in beta.

        '
      tags:
      - Forward Geocoding
      parameters:
      - name: address
        in: query
        description: Street address with optional house number
        schema:
          type: string
        example: 30 West 26th Street
      - name: neighbourhood
        in: query
        description: Neighbourhood name (vernacular geographic entity)
        schema:
          type: string
        example: Notting Hill
      - name: borough
        in: query
        description: Borough name (sub-locality division)
        schema:
          type: string
        example: Manhattan
      - name: locality
        in: query
        description: City or locality name
        schema:
          type: string
        example: New York
      - name: county
        in: query
        description: County or administrative division between locality and region
        schema:
          type: string
        example: Bucks
      - name: region
        in: query
        description: State, province, or first-level administrative division
        schema:
          type: string
        example: NY
      - name: postalcode
        in: query
        description: Postal or ZIP code
        schema:
          type: string
        example: '10001'
      - name: country
        in: query
        description: Country name or ISO-3166 alpha-2/alpha-3 code
        schema:
          type: string
        example: US
      - $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.country'
      - $ref: '#/components/parameters/sources'
      - $ref: '#/components/parameters/layers'
      responses:
        '200':
          description: GeoJSON FeatureCollection of geocoding results
          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.circle.lon:
      name: boundary.circle.lon
      in: query
      description: Longitude of the center of a circular boundary
      schema:
        type: number
        format: float
    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.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
  examples:
    YMCASearch:
      summary: Search for YMCA worldwide
      value:
        geocoding:
          version: '1.0'
          attribution: https://geocode.earth/guidelines
          query:
            text: YMCA
            size: 10
            private: false
            lang:
              name: English
              iso6391: en
              iso6393: eng
              defaulted: true
          engine:
            name: Pelias
            author: Mapzen
            version: '1.0'
          timestamp: 1525718151924
        type: FeatureCollection
        features:
        - type: Feature
          geometry:
            type: Point
            coordinates:
            - -3.178491
            - 51.675098
          properties:
            id: '1234567'
            gid: openstreetmap:venue:1234567
            layer: venue
            source: openstreetmap
            name: YMCA
            confidence: 0.9
            country: United Kingdom
            country_a: GBR
            locality: Bargoed
            label: YMCA, Bargoed Community, United Kingdom
  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