openapi: 3.0.0
servers:
  - url: "https://api.tomtom.com"
info:
  contact:
    name: Contact Us
    url: "https://developer.tomtom.com/contact-us"
    x-twitter: TomTom
  description: "Search API is a RESTful API that allows developers to run a single line fuzzy search for addresses and POIs. Search API returns the latitude/longitude of a specific address, cross street, geographic feature, or point of interest (POI)."
  title: Search
  version: 1.0.0

security:
  - api_key: []
paths:
  "/search/{versionNumber}/additionalData.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Expected response format.
          in: path
          name: ext
          required: true
          schema:
            enum:
              - json
            type: string
        - description: "Comma separated list of geometry UUIDs, previously retrieved from an Search API request."
          example: "00004631-3400-3c00-0000-0000673c4d2e,00004631-3400-3c00-0000-0000673c42fe"
          in: query
          name: geometries
          required: true
          schema:
            type: string
        - description: Defines the precision of the geometries.
          in: query
          name: geometriesZoom
          schema:
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
              - 19
              - 20
              - 21
              - 22
            type: integer
      responses:
        "200":
          description: "OK: additional data were retrieved and the body of the response contains requested data."
        "400":
          description: "Bad request: one or more parameters(i.e. geometries, ext) were incorrectly specified."
        "403":
          description: |-
            Permission, capacity, or authentication issues:
              - Forbidden
              - Not authorized
              - Account inactive
              - Account over queries per second limit
              - Account over rate limit
              - Rate limit exceeded
        "404":
          description: "Not Found: the requested resource could not be found, but it may be available again in the future."
        "405":
          description: "Method Not Allowed: the client used a HTTP method other than GET."
        "408":
          description: Request timeout.
        "414":
          description: Requested uri is too long.
        "500":
          description: An error occurred while processing the request. Please try again later.
        "502":
          description: Internal network connectivity issue.
        "503":
          description: Service currently unavailable.
        "504":
          description: Internal network connectivity issue or a request that has taken too long to complete.
        "596":
          description: Service not found.
      summary: Additional Data
      tags:
        - Additional Data
  "/search/{versionNumber}/cS/{category}.{ext}":
    get:
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: category
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/idxSet"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Low Bandwith Category Search
      tags:
        - Search
  "/search/{versionNumber}/categorySearch/{query}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Category Search
      tags:
        - Search
  "/search/{versionNumber}/geocode/{query}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: 4 north 2nd street san jose
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/storeResult"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Geocode
      tags:
        - Geocoding
  "/search/{versionNumber}/geometryFilter.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/ext"
        - description: List of geometries to filter by. Available types are CIRCLE (with the radius expressed in meters) and POLYGON.
          example: '[{"type":"CIRCLE", "position":"40.80558, -73.96548", "radius":100}, {"type":"POLYGON", "vertices":["37.7524152343544, -122.43576049804686", "37.70660472542312, -122.43301391601562", "37.712059855877314, -122.36434936523438", "37.75350561243041, -122.37396240234374"]}]'
          in: query
          name: geometryList
          required: true
          schema:
            type: string
        - description: "List of POIs to filter. The only required attribute of a POI is position, everything else is optional and will be echoed back when passed in."
          example: '[{"poi":{"name":"S Restaurant Toms"},"address":{"freeformAddress":"2880 Broadway, New York, NY 10025"},"position":{"lat":40.80558,"lon":-73.96548}},{"poi":{"name":"Yasha Raman Corporation"},"address":{"freeformAddress":"940 Amsterdam Ave, New York, NY 10025"},"position":{"lat":40.80076,"lon":-73.96556}}]'
          in: query
          name: poiList
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Geometry Filter
      tags:
        - Filters
    post:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/ext"
      requestBody:
        content:
          application/json:
            schema:
              example:
                geometryList:
                  - position: "40.80558,-73.96548"
                    radius: 100
                    type: CIRCLE
                  - type: POLYGON
                    vertices:
                      - "37.7524152343544,-122.43576049804686"
                      - "37.70660472542312,-122.43301391601562"
                      - "37.712059855877314,-122.36434936523438"
                      - "37.75350561243041,-122.37396240234374"
                poiList:
                  - address:
                      freeformAddress: "2880 Broadway, New York, NY 10025"
                    poi:
                      name: S Restaurant Tom's
                    position:
                      lat: 40.80558
                      lon: -73.96548
              properties:
                geometryList:
                  items:
                    properties:
                      position:
                        type: string
                      radius:
                        type: integer
                      type:
                        type: string
                      vertices:
                        items:
                          type: string
                        type: array
                    type: object
                  type: array
                poiList:
                  items:
                    properties:
                      address:
                        properties:
                          freeformAddress:
                            type: string
                        type: object
                      poi:
                        properties:
                          name:
                            type: string
                        type: object
                      position:
                        properties:
                          lat:
                            format: float
                            type: number
                          lon:
                            format: float
                            type: number
                        type: object
                    type: object
                  type: array
              type: object
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Geometry Filter
      tags:
        - Filters
  "/search/{versionNumber}/geometrySearch/{query}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - description: List of geometries to filter by. Available types are CIRCLE (with the radius expressed in meters) and POLYGON.
          example: '[{"type":"POLYGON", "vertices":["37.7524152343544, -122.43576049804686", "37.70660472542312, -122.43301391601562", "37.712059855877314, -122.36434936523438", "37.75350561243041, -122.37396240234374"]}, {"type":"CIRCLE", "position":"37.71205, -121.36434", "radius":6000}, {"type":"CIRCLE", "position":"37.31205, -121.36434", "radius":1000}]'
          in: query
          name: geometryList
          schema:
            type: string
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/idxSet"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Geometry Search
      tags:
        - Search
    post:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/idxSet"
      requestBody:
        content:
          application/json:
            schema:
              example:
                geometryList:
                  - type: POLYGON
                    vertices:
                      - "37.7524152343544,-122.43576049804686"
                      - "37.70660472542312,-122.43301391601562"
                      - "37.712059855877314,-122.36434936523438"
                      - "37.75350561243041,-122.37396240234374"
                  - position: "37.71205,-121.36434"
                    radius: 6000
                    type: CIRCLE
                  - position: "37.31205,-121.36434"
                    radius: 1000
                    type: CIRCLE
              properties:
                geometryList:
                  items:
                    properties:
                      position:
                        type: string
                      radius:
                        type: integer
                      type:
                        type: string
                      vertices:
                        items:
                          type: string
                        type: array
                    type: object
                  type: array
              type: object
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Geometry Search
      tags:
        - Search
  "/search/{versionNumber}/nearbySearch/.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/ext"
        - description: |-
            Latitude where results should be biased.  
            NOTE: supplying a lat/lon without a radius will return search results biased to that point.
          example: 37.337
          in: query
          name: lat
          required: true
          schema:
            format: float
            type: number
        - description: |-
            Longitude where results should be biased
            NOTE: supplying a lat/lon without a radius will return search results biased to that point.
          example: -121.89
          in: query
          name: lon
          required: true
          schema:
            format: float
            type: number
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - description: "If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters."
          in: query
          name: radius
          schema:
            default: 10000
            maximum: 50000
            type: integer
        - deprecated: true
          description: "Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon."
          example: "37.553,-122.453"
          in: query
          name: topLeft
          schema:
            type: string
        - deprecated: true
          description: "Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon."
          example: "37.4,-122.55"
          in: query
          name: btmRight
          schema:
            type: string
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/minFuzzyLevel"
        - $ref: "#/components/parameters/maxFuzzyLevel"
        - $ref: "#/components/parameters/idxSet"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Nearby Search
      tags:
        - Search
  "/search/{versionNumber}/poiSearch/{query}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Points of Interest Search
      tags:
        - Search
  "/search/{versionNumber}/reverseGeocode/crossStreet/{position}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/position"
        - $ref: "#/components/parameters/ext"
        - description: Maximum number of cross-streets to return.
          in: query
          name: limit
          schema:
            default: 1
            maximum: 100
            minimum: 0
            type: integer
        - deprecated: true
          description: 'If the "spatialKeys" flag is set, the response will also contain a proprietary geospatial keys for a specified location.'
          in: query
          name: spatialKeys
          schema:
            default: false
            type: boolean
        - description: "The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)"
          in: query
          name: heading
          schema:
            format: float
            type: number
        - description: The maximum distance in meters from the specified position for the reverse geocoder to consider.
          in: query
          name: radius
          schema:
            default: 10000
            type: integer
        - $ref: "#/components/parameters/language"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Cross Street Lookup
      tags:
        - Reverse Geocoding
  "/search/{versionNumber}/reverseGeocode/{position}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/position"
        - $ref: "#/components/parameters/ext"
        - deprecated: true
          description: 'If the "spatialKeys" flag is set, the response will also contain a proprietary geospatial keys for a specified location.'
          in: query
          name: spatialKeys
          schema:
            default: false
            type: boolean
        - description: To enable return of the posted speed limit (where available).
          in: query
          name: returnSpeedLimit
          schema:
            default: false
            type: boolean
        - description: "The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)"
          in: query
          name: heading
          schema:
            format: float
            type: number
        - description: The maximum distance in meters from the specified position for the reverse geocoder to consider.
          in: query
          name: radius
          schema:
            default: 10000
            type: integer
        - description: "If a number is sent in along with the request, the response may include the side of the street (Left/Right) and an offset position for that number."
          in: query
          name: number
          schema:
            type: string
        - description: Enables return of the road use array for reverse geocodes at street level.
          in: query
          name: returnRoadUse
          schema:
            default: false
            type: boolean
        - description: 'Restricts reverse geocodes to a certain type of road use. The road use array for reverse geocodes can be one or more of: ["LimitedAccess", "Arterial", "Terminal", "Ramp", "Rotary", "LocalStreet"].'
          in: query
          name: roadUse
          schema:
            type: string
        - description: Specifies the jsonp callback method.
          in: query
          name: callback
          schema:
            default: cb
            type: string
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Reverse Geocode
      tags:
        - Reverse Geocoding
  "/search/{versionNumber}/routedFilter/{position}/{heading}.{ext}":
    get:
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/position"
        - description: "The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)"
          example: -15.6
          in: path
          name: heading
          required: true
          schema:
            format: float
            type: number
        - $ref: "#/components/parameters/ext"
        - description: "List of POIs to filter. The only required attribute of a POI is position, everything else is optional and will be echoed back when passed in."
          example: '[{"poi":{"name":"Cleaire Advanced Emission Controls"},"address":{"freeformAddress":"7220 Trade St, San Diego, CA 92121"},"position":{"lat":"37.83274","lon":"-122.27631"}}]'
          in: query
          name: poiList
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/routingTimeout"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Routed Filter
      tags:
        - Filters
    post:
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/position"
        - description: "The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)"
          example: 90
          in: path
          name: heading
          required: true
          schema:
            format: float
            type: number
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/routingTimeout"
      requestBody:
        content:
          application/json:
            schema:
              example:
                poiList:
                  - address:
                      freeformAddress: "9500 Gilman Dr, San Diego, CA 92037"
                    poi:
                      name: University of California San Diego
                    position:
                      lat: 32.87349
                      lon: -117.2378
                  - address:
                      freeformAddress: "7220 Trade St, San Diego, CA 92121"
                    poi:
                      name: Cleaire Advanced Emission Controls
                    position:
                      lat: 37.83274
                      lon: -122.27631
              properties:
                poiList:
                  items:
                    properties:
                      address:
                        properties:
                          freeformAddress:
                            type: string
                        type: object
                      poi:
                        properties:
                          name:
                            type: string
                        type: object
                      position:
                        properties:
                          lat:
                            format: float
                            type: number
                          lon:
                            format: float
                            type: number
                        type: object
                    type: object
                  type: array
              type: object
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Routed Filter
      tags:
        - Filters
  "/search/{versionNumber}/routedSearch/{query}/{position}/{heading}.{ext}":
    get:
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: gas
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/position"
        - description: "The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)"
          example: 90
          in: path
          name: heading
          required: true
          schema:
            format: float
            type: number
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - description: "Multiplies the limit by N to gather more candidate POIs, which will then be sorted by drive distance, returning only the top candidates according to the limit."
          in: query
          name: multiplier
          schema:
            default: 2
            type: integer
        - $ref: "#/components/parameters/routingTimeout"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/idxSet"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Routed Search
      tags:
        - Search
  "/search/{versionNumber}/s/{query}.{ext}":
    get:
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/idxSet"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Low Bandwith Search
      tags:
        - Search
  "/search/{versionNumber}/search/{query}.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: |-
            Query string. Must be properly URL encoded.

            To perform a reverse geocode, the user can provide latitude and longitude coordinates directly in the query. More information can be found <a href="/search-api/search-api-documentation-search/fuzzy-search#AdditionalInfo">here</a>.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/typeahead"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/countrySet"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/radius"
        - $ref: "#/components/parameters/topLeft"
        - $ref: "#/components/parameters/btmRight"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
        - $ref: "#/components/parameters/minFuzzyLevel"
        - $ref: "#/components/parameters/maxFuzzyLevel"
        - $ref: "#/components/parameters/idxSet"
        - $ref: "#/components/parameters/view"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Fuzzy Search
      tags:
        - Search
  "/search/{versionNumber}/searchAlongRoute/{query}.{ext}":
    post:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - description: Query string. Must be properly URL encoded.
          example: pizza
          in: path
          name: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ext"
        - description: Maximum detour time
          example: 1200
          in: query
          name: maxDetourTime
          required: true
          schema:
            maximum: 3600
            type: integer
        - $ref: "#/components/parameters/limit"
      requestBody:
        content:
          application/json:
            schema:
              example:
                route:
                  points:
                    - lat: 37.7524152343544
                      lon: -122.43576049804686
                    - lat: 37.70660472542312
                      lon: -122.43301391601562
                    - lat: 37.712059855877314
                      lon: -122.36434936523438
                    - lat: 37.75350561243041
                      lon: -122.37396240234374
              properties:
                route:
                  properties:
                    points:
                      items:
                        properties:
                          lat:
                            format: float
                            type: number
                          lon:
                            format: float
                            type: number
                        type: object
                      type: array
                  type: object
              type: object
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Along Route Search
      tags:
        - Search
  "/search/{versionNumber}/structuredGeocode.{ext}":
    get:
      parameters:
        - $ref: "#/components/parameters/versionNumber"
        - $ref: "#/components/parameters/ext"
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/ofs"
        - $ref: "#/components/parameters/streetNumber"
        - $ref: "#/components/parameters/streetName"
        - $ref: "#/components/parameters/crossStreet"
        - $ref: "#/components/parameters/municipality"
        - $ref: "#/components/parameters/municipalitySubdivision"
        - $ref: "#/components/parameters/countryTertiarySubdivision"
        - $ref: "#/components/parameters/countrySecondarySubdivision"
        - $ref: "#/components/parameters/countrySubdivision"
        - $ref: "#/components/parameters/postalCode"
        - $ref: "#/components/parameters/language"
        - $ref: "#/components/parameters/extendedPostalCodesFor"
      responses:
        "200":
          $ref: "#/components/responses/200"
        "400":
          $ref: "#/components/responses/400"
        "403":
          $ref: "#/components/responses/403"
        "405":
          $ref: "#/components/responses/405"
        404/596:
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Structured Geocode
      tags:
        - Geocoding
components:
  parameters:
    btmRight:
      description: "Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon."
      example: "37.4,-122.55"
      in: query
      name: btmRight
      schema:
        type: string
    countryCode:
      description: "2 or 3 letter country code (e.g.: FR, ES)."
      example: NL
      in: query
      name: countryCode
      required: true
      schema:
        type: string
    countrySecondarySubdivision:
      description: The county for the structured address.
      in: query
      name: countrySecondarySubdivision
      schema:
        type: string
    countrySet:
      description: Comma separated string of country codes. This will limit the search to the specified countries.
      example: FR
      in: query
      name: countrySet
      schema:
        type: string
    countrySubdivision:
      description: The state or province for the structured address.
      in: query
      name: countrySubdivision
      schema:
        type: string
    countryTertiarySubdivision:
      description: The named area for the structured address.
      in: query
      name: countryTertiarySubdivision
      schema:
        type: string
    crossStreet:
      description: The cross street name for the structured address.
      in: query
      name: crossStreet
      schema:
        type: string
    ext:
      description: Expected response format.
      example: xml
      in: path
      name: ext
      required: true
      schema:
        enum:
          - json
          - jsonp
          - js
          - xml
        type: string
    extendedPostalCodesFor:
      description: |-
        Indexes for which extended postal codes should be included in the results. Available indexes are:
          - <b>Addr</b> = Address ranges
          - <b>Geo</b> = Geographies
          - <b>PAD</b> = Point Addresses
          - <b>POI</b> = Points of Interest
          - <b>Str</b> = Streets
          - <b>XStr</b> = Cross Streets (intersections)
      in: query
      name: extendedPostalCodesFor
      schema:
        type: string
    idxSet:
      description: |-
        A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are:
          - <b>Addr</b> = Address range interpolation (when there is no PAD)
          - <b>Geo</b> = Geographies
          - <b>PAD</b> = Point Addresses
          - <b>POI</b> = Points of interest
          - <b>Str</b> = Streets
          - <b>Xstr</b> = Cross Streets (intersections)
      example: POI
      in: query
      name: idxSet
      schema:
        type: string
    language:
      description: 'Language in which search results should be returned. Should be one of <a href="/search-api/search-api-documentation/supported-languages">supported IETF language tags</a>, case insensitive.'
      in: query
      name: language
      schema:
        type: string
    lat:
      description: |-
        Latitude where results should be biased.  
        NOTE: supplying a lat/lon without a radius will return search results biased to that point.
      example: 37.337
      in: query
      name: lat
      schema:
        format: float
        type: number
    limit:
      description: Maximum number of search results that will be returned.
      in: query
      name: limit
      schema:
        default: 10
        maximum: 100
        type: integer
    lon:
      description: |-
        Longitude where results should be biased
        NOTE: supplying a lat/lon without a radius will return search results biased to that point.
      example: -121.89
      in: query
      name: lon
      schema:
        format: float
        type: number
    maxFuzzyLevel:
      description: Maximum fuzziness level to be used.
      in: query
      name: maxFuzzyLevel
      schema:
        default: 2
        maximum: 4
        minimum: 1
        type: integer
    minFuzzyLevel:
      description: Minimum fuzziness level to be used.
      in: query
      name: minFuzzyLevel
      schema:
        default: 1
        maximum: 4
        minimum: 1
        type: integer
    municipality:
      description: The municipality (city/town) for the structured address.
      example: Amsterdam
      in: query
      name: municipality
      schema:
        type: string
    municipalitySubdivision:
      description: The municipality subdivision (sub/super city) for the structured address.
      in: query
      name: municipalitySubdivision
      schema:
        type: string
    ofs:
      description: Starting offset of the returned results within the full result set.
      in: query
      name: ofs
      schema:
        default: 0
        maximum: 1900
        type: integer
    position:
      description: "This is specified as a comma separated string composed of lat., lon."
      example: "37.8328,-122.27669"
      in: path
      name: position
      required: true
      schema:
        type: string
    postalCode:
      description: The zip code or postal code for the structured address.
      in: query
      name: postalCode
      schema:
        type: string
    radius:
      description: "If radius <b>and</b> position are set, the results will be constrained to the defined area. The radius parameter is specified in meters."
      in: query
      name: radius
      schema:
        type: integer
    routingTimeout:
      description: Only return results that arrive from routing engine within this time limit.
      in: query
      name: routingTimeout
      schema:
        default: 4000
        type: integer
    storeResult:
      deprecated: true
      description: 'If the "storeResult" flag is set, the query will be interpreted as a stored geocode and will be billed according to the terms of use.'
      in: query
      name: storeResult
      schema:
        default: false
        type: boolean
    streetName:
      description: The street name for the structured address.
      in: query
      name: streetName
      schema:
        type: string
    streetNumber:
      description: The street number for the structured address.
      in: query
      name: streetNumber
      schema:
        type: string
    topLeft:
      description: "Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon."
      example: "37.553,-122.453"
      in: query
      name: topLeft
      schema:
        type: string
    typeahead:
      description: 'If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter <b>predictive</b> mode.'
      in: query
      name: typeahead
      schema:
        default: false
        type: boolean
    versionNumber:
      description: Service version number. The current value is 2.
      in: path
      name: versionNumber
      required: true
      schema:
        enum:
          - 2
        type: integer
    view:
      description: Geopolitical View.
      in: query
      name: view
      required: false
      schema:
        default: Unified
        enum:
          - Unified
          - IN
          - PK
          - IL
          - MA
        type: string
  responses:
    "200":
      description: "OK: the search successfully returned zero or more results."
    "400":
      description: "Bad Request: one or more parameters were incorrectly specified."
    "403":
      description: |-
        Forbidden: possible causes include:
          - Service requires SSL
          - Not authorized
          - Rate or volume limit exceeded
          - Unknown referer
    "405":
      description: "Method Not Allowed: the HTTP method (GET, POST, etc) is not supported for this request."
    "404596":
      description: "Not Found: the HTTP request method (GET, POST, etc) or path is incorrect."
    5xx:
      description: An error occurred while processing the request. Please try again later.
  securitySchemes:
    api_key:
      in: query
      name: key
      type: apiKey