openapi: 3.0.3
info:
  title: Pelias 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
externalDocs:
  description: Pelias Documentation
  url: 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
  - name: Reverse Geocoding
    description: Convert geographic coordinates into places and addresses
  - name: Autocomplete
    description: Real-time type-ahead geocoding for user input
  - name: Place Lookup
    description: Retrieve details for a known place by ID

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'

  /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'

  /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'

  /place:
    get:
      operationId: lookupPlace
      summary: Look up place details by Pelias GID
      description: >
        Returns details for one or more places identified by their Pelias Global Identifier (gid).
        GIDs are returned in search/autocomplete/reverse results and should not be constructed
        manually. Note that GeoNames and Who's on First have stable IDs; OpenAddresses and
        OpenStreetMap IDs may change across data imports.
      tags:
        - Place Lookup
      parameters:
        - name: ids
          in: query
          required: true
          description: >
            Comma-separated list of Pelias gid values (e.g.
            openstreetmap:venue:way/5013364,whosonfirst:borough:421205771)
          schema:
            type: string
          example: "openstreetmap:venue:way/5013364"
        - name: categories
          in: query
          description: When present, includes category metadata in the response
          schema:
            type: boolean
          allowEmptyValue: true
      responses:
        '200':
          description: GeoJSON FeatureCollection with place details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  parameters:
    text:
      name: text
      in: query
      required: true
      description: Free-form text to geocode (addresses, place names, etc.)
      schema:
        type: string
      example: "YMCA"

    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

    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"

    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

    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.min_lon:
      name: boundary.rect.min_lon
      in: query
      description: Minimum longitude of rectangular boundary (western edge)
      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_lat:
      name: boundary.rect.min_lat
      in: query
      description: Minimum latitude of rectangular boundary (southern edge)
      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.lat:
      name: boundary.circle.lat
      in: query
      description: Latitude of the center of a circular boundary
      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.circle.radius:
      name: boundary.circle.radius
      in: query
      description: Radius in km of the 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.gid:
      name: boundary.gid
      in: query
      description: Pelias gid of an administrative area to restrict results within
      schema:
        type: string
      example: "whosonfirst:locality:101748355"

    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"

    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

    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

    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: []

  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"

    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"