openapi: 3.0.3
info:
  description: 'Confidently create beautiful maps for all your users with our tools. Choose your style from our library or build your own. With a rich palette of choices to fit any context and support for dozens of languages and scripts, you can deliver a quality experience for your customers no matter what part of the globe they call home. '
  version: 7.1.0
  title: Stadia Maps Reverse API
  contact:
    name: Stadia Maps Support
    url: https://www.stadiamaps.com
    email: support@stadiamaps.com
servers:
- url: https://api.stadiamaps.com
- url: https://api-eu.stadiamaps.com
tags:
- name: Reverse
paths:
  /geocoding/v1/reverse:
    get:
      tags:
      - Reverse
      operationId: reverse
      summary: Find places and addresses near geographic coordinates (reverse geocoding).
      description: Reverse geocoding and search finds places and addresses near any geographic coordinates.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/reverseLat'
      - $ref: '#/components/parameters/reverseLon'
      - $ref: '#/components/parameters/searchBoundaryCircleRadius'
      - $ref: '#/components/parameters/searchLayers'
      - $ref: '#/components/parameters/searchSources'
      - $ref: '#/components/parameters/searchBoundaryCountry'
      - $ref: '#/components/parameters/searchBoundaryGID'
      - $ref: '#/components/parameters/size'
      - $ref: '#/components/parameters/peliasLang'
      responses:
        '200':
          description: A GeoJSON collection of search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/peliasResponse'
        '400':
          description: Bad request
components:
  parameters:
    peliasLang:
      name: lang
      in: query
      schema:
        $ref: '#/components/schemas/peliasLang'
      description: A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.
    searchBoundaryCircleRadius:
      name: boundary.circle.radius
      in: query
      schema:
        $ref: '#/components/schemas/searchBoundaryCircleRadius'
      description: The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified.
    searchBoundaryGID:
      name: boundary.gid
      in: query
      schema:
        $ref: '#/components/schemas/searchBoundaryGID'
      description: The Pelias GID of an area to limit the search to.
    size:
      name: size
      in: query
      schema:
        $ref: '#/components/schemas/limit'
      description: The maximum number of results to return.
    reverseLat:
      name: point.lat
      in: query
      schema:
        $ref: '#/components/schemas/reverseLat'
      description: The latitude of the point at which to perform the search.
      required: true
    searchBoundaryCountry:
      name: boundary.country
      in: query
      schema:
        $ref: '#/components/schemas/searchBoundaryCountry'
      description: 'A list of countries to limit the search to. These may be either full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer ISO codes when possible.'
      style: form
      explode: false
    reverseLon:
      name: point.lon
      in: query
      schema:
        $ref: '#/components/schemas/reverseLon'
      description: The longitude of the point at which to perform the search.
      required: true
    searchSources:
      name: sources
      in: query
      schema:
        $ref: '#/components/schemas/searchSources'
      description: A list of sources to limit the search to.
      style: form
      explode: false
    searchLayers:
      name: layers
      in: query
      schema:
        $ref: '#/components/schemas/searchLayers'
      description: A list of layers to limit the search to.
      style: form
      explode: false
  schemas:
    reverseLon:
      type: number
      description: The longitude of the point at which to perform the search.
      example: 2.294471
      format: double
      minimum: -180
      maximum: 180
    limit:
      type: integer
      description: The maximum number of results to return.
    peliasLayer:
      type: string
      enum:
      - venue
      - address
      - street
      - country
      - macroregion
      - region
      - macrocounty
      - county
      - locality
      - localadmin
      - borough
      - neighbourhood
      - postalcode
      - coarse
      - dependency
      - macrohood
      - marinearea
      - disputed
      - empire
      - continent
      - ocean
      description: 'Our database is organized into several layers (in the GIS sense of the term) as follows:


        - `venue`: Points of interest, businesses, and things with walls

        - `address`: Places with a street address

        - `street`: Streets, roads, highways

        - `county`: Places that issue passports, nations, nation-states

        - `macroregion`: A related group of regions (mostly in Europe)

        - `region`: The first administrative division within a country (usually states and provinces)

        - `macrocounty`: A related group of counties (mostly in Europe)

        - `county`: Official governmental areas; usually bigger than a locality, but almost always smaller than a region

        - `locality`: Towns, hamlets, cities, etc.

        - `localadmin`: Local administrative boundaries

        - `borough`: Local administrative boundaries within cities (not widely used, but present in places such as NYC and Mexico City)

        - `neighbourhood`: Social communities and neighborhoods (note the British spelling in the API!)

        - `postalcode`: Postal codes used by mail services (note: not used for reverse geocoding)

        - `coarse`: An alias for simultaneously using all administrative layers (everything except `venue` and `address`)

        - `marinearea`: Places with fishes and boats.

        - `ocean`: A really big marine area.

        '
    peliasGeoJSONFeature:
      type: object
      required:
      - type
      - geometry
      properties:
        type:
          type: string
          enum:
          - Feature
        geometry:
          $ref: '#/components/schemas/geoJSONPoint'
        properties:
          $ref: '#/components/schemas/peliasGeoJSONProperties'
        bbox:
          type: array
          minItems: 4
          maxItems: 4
          items:
            type: number
            format: double
          description: An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
    searchBoundaryCountry:
      type: array
      items:
        type: string
      description: 'A list of countries to limit the search to. These may be either full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer ISO codes when possible.'
    peliasResponse:
      type: object
      properties:
        geocoding:
          allOf:
          - $ref: '#/components/schemas/geocodingObject'
        bbox:
          type: array
          minItems: 4
          maxItems: 4
          items:
            type: number
            format: double
          description: An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
        features:
          type: array
          items:
            $ref: '#/components/schemas/peliasGeoJSONFeature'
      required:
      - geocoding
      - features
      example:
        geocoding:
          version: '0.2'
          attribution: https://stadiamaps.com/attribution
          query:
            text: 1600 Pennsylvania Ave NW
            size: 10
            private: false
            lang:
              name: English
              iso6391: en
              iso6393: eng
              via: default
              defaulted: true
            querySize: 20
            parser: libpostal
            parsed_text:
              housenumber: '1600'
              street: pennsylvania ave nw
          engine:
            name: Pelias
            author: Mapzen
            version: '1.0'
          timestamp: 1679043782383
        type: FeatureCollection
        features:
        - type: Feature
          geometry:
            type: Point
            coordinates:
            - -77.036547
            - 38.897675
          properties:
            id: us/dc/statewide:aa53d4bd0fe295be
            gid: openaddresses:address:us/dc/statewide:aa53d4bd0fe295be
            layer: address
            source: openaddresses
            source_id: us/dc/statewide:aa53d4bd0fe295be
            country_code: US
            name: 1600 Pennsylvania Avenue NW
            housenumber: '1600'
            street: Pennsylvania Avenue NW
            postalcode: '20500'
            confidence: 1
            match_type: exact
            accuracy: point
            country: United States
            country_gid: whosonfirst:country:85633793
            country_a: USA
            region: District of Columbia
            region_gid: whosonfirst:region:85688741
            region_a: DC
            county: District of Columbia
            county_gid: whosonfirst:county:1377370667
            county_a: DI
            locality: Washington
            locality_gid: whosonfirst:locality:85931779
            neighbourhood: White House Grounds
            neighbourhood_gid: whosonfirst:neighbourhood:1108724059
            continent: North America
            continent_gid: whosonfirst:continent:102191575
            label: 1600 Pennsylvania Avenue NW, Washington, DC, USA
        bbox:
        - -77.036547
        - 38.897675
        - -77.036547
        - 38.897675
    geoJSONGeometryBase:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - Point
          - MultiPoint
          - LineString
          - MultiLineString
          - Polygon
          - MultiPolygon
    searchBoundaryCircleRadius:
      type: number
      description: The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified.
      format: double
    searchLayers:
      type: array
      description: A list of layers to limit the search to.
      items:
        $ref: '#/components/schemas/peliasLayer'
    peliasGeoJSONProperties:
      type: object
      additionalProperties: true
      properties:
        gid:
          type: string
          description: A scoped GID for this result. This can be passed to the place endpoint. Note that these are not always stable. For Geonames and Who's on First, these are usually stable, but for other sources like OSM, no stability is guaranteed.
        source_id:
          type: string
          description: An ID referencing the original data source (specified via source) for the result. These IDs are specific to the source that they originated from. For example, in the case of OSM, these typically look like way/123 or point/123.
        label:
          type: string
          description: 'A full, human-readable label. However, you may not necessarily want to use this; be sure to read the docs for name, locality, and region before making a decision. This field is mostly localized. The order of components is generally locally correct (ex: for an address in South Korea, the house number appears after the street name). However, components will use a request language equivalent if one exists (ex: Seoul instead of � if lang=en).'
        layer:
          $ref: '#/components/schemas/peliasLayer'
        name:
          type: string
          description: The name of the place, the street address including house number, or label of similar relevance. If your app is localized to a specific region, you may get better display results by combining name, locality OR region (or neither?), and postal code together in the local format. Experiment with what works best for your use case.
        accuracy:
          type: string
          enum:
          - point
          - centroid
          description: 'The accuracy of the geographic coordinates in the result. This value is a property of the result itself and won''t change based on the query.

            A point result means that the record can reasonably be represented by a single geographic point. Addresses, venues, or interpolated addresses usually have point accuracy.

            Larger areas, such as a city or country, cannot be represented by a single point, so a centroid is given instead.'
        addendum:
          type: object
          additionalProperties: true
          description: 'Optional additional information from the underlying data source (ex: OSM). This includes select fields. The most useful fields are mapped in the definition here, but others may be available.'
          properties:
            osm:
              type: object
              additionalProperties: true
              properties:
                website:
                  type: string
                  format: uri
                wikipedia:
                  type: string
                wikidata:
                  type: string
                phone:
                  type: string
        continent:
          type: string
        continent_gid:
          type: string
        country:
          type: string
        country_gid:
          type: string
        neighbourhood:
          type: string
        neighbourhood_gid:
          type: string
        borough:
          type: string
        borough_gid:
          type: string
        postalcode:
          type: string
        street:
          type: string
        housenumber:
          type: string
        locality:
          type: string
          description: The city, village, town, etc. that the place / address is part of. Note that values may not always match postal or local conventions perfectly.
        locality_gid:
          type: string
        county:
          type: string
          description: Administrative divisions between localities and regions. Useful for disambiguating nearby results with similar names.
        region:
          type: string
          description: Typically the first administrative division within a country. For example, a US state or a Canadian province.
        region_a:
          type: string
          description: The abbreviation for the region.
    searchBoundaryGID:
      type: string
      description: The Pelias GID of an area to limit the search to.
    searchSources:
      type: array
      description: A list of sources to limit the search to.
      items:
        $ref: '#/components/schemas/peliasSource'
    geoJSONPoint:
      allOf:
      - $ref: '#/components/schemas/geoJSONGeometryBase'
      - type: object
        required:
        - coordinates
        properties:
          coordinates:
            type: array
            minItems: 2
            maxItems: 3
            items:
              type: number
              format: double
    peliasSource:
      type: string
      enum:
      - openstreetmap
      - openaddresses
      - whosonfirst
      - geonames
      description: Our database contains info from multiple sources. These identifiers can be used to either limit search results or to determine the relevance of a result.
    reverseLat:
      type: number
      description: The latitude of the point at which to perform the search.
      example: 48.848268
      format: double
      minimum: -90
      maximum: 90
    geocodingObject:
      type: object
      properties:
        attribution:
          type: string
          format: uri
          description: A URL containing attribution information. If you are not using Stadia Maps and our standard attribution already for your basemaps, you must include this attribution link somewhere in your website/app.
        query:
          type: object
          additionalProperties: true
          description: Technical details of the query. This is most useful for debugging during development. See the full example for the list of properties; these should be self-explanatory, so we don't enumerate them in the spec.
        warnings:
          type: array
          items:
            type: string
          description: An array of non-critical warnings. This is normally for informational/debugging purposes and not a serious problem.
        errors:
          type: array
          items:
            type: string
          description: An array of more serious errors (for example, omitting a required parameter). Dont ignore these.
    peliasLang:
      type: string
      description: A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key