--- 
components: 
  parameters: 
    allowFreeformNewLine: 
      description: "The format of new lines in the formatted adress."
      in: query
      name: allowFreeformNewLine
      schema: 
        default: false
        type: boolean
    brandSet: 
      description: "A comma-separated list of brand names which could be used to restrict the result to Points Of Interest of specific brands."
      in: query
      name: brandSet
      schema: 
        type: string
    btmRight: 
      description: "Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon."
      in: query
      name: btmRight
      schema: 
        type: string
    categorySet: 
      description: |-
          A comma-separated list of categories which could be used to restrict the result to Points Of Interest of specific categories. The list of categories can be discovered using the <a href="/search-api/search-api-documentation/poi-categories" target="_blank">POI Categories endpoint</a>.
          Note: In the following "example:", "7315" indicates a "restaurant".
      in: query
      name: categorySet
      schema: 
        type: string
    connectorSet: 
      description: "A comma-separated list of connector types which could be used to restrict the result to Points Of Interest of type Electric Vehicle Station supporting specific connector types. <a href=\"/search-api/search-api-documentation/supported-connector-types\" target=\"_blank\">List of supported connector types</a>."
      in: query
      name: connectorSet
      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."
      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
    entityTypeSet: 
      description: "A comma-separated list of entity types which can be used to restrict the result to the Geography result of a specific entity type. If entityTypeSet is specified, only a Geography result with a proper entity type will be returned."
      in: query
      name: entityTypeSet
      schema: 
        enum: 
          - Country
          - CountrySubdivision
          - CountrySecondarySubdivision
          - CountryTertiarySubdivision
          - Municipality
          - MunicipalitySubdivision
          - Neighbourhood
          - PostalCodeArea
        type: string
    ext: 
      description: "Expected response format."
      example: json
      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
    fuelSet: 
      description: "A comma-separated list of fuel types which could be used to restrict the result to the Points Of Interest of specific fuels. If fuelSet is specified, the query can remain empty. Only POIs with a proper fuel type will be returned."
      explode: false
      in: query
      name: fuelSet
      schema: 
        items: 
          enum: 
            - Petrol
            - LPG
            - Diesel
            - Biodiesel
            - DieselForCommercialVehicles
            - E85
            - LNG
            - CNG
            - Hydrogen
            - AdBlue
        type: array
    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)
      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
        maximum: 90
        minimum: -90
        type: number
    limit: 
      description: "Maximum number of search results that will be returned."
      in: query
      name: limit
      schema: 
        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
        maximum: 180
        minimum: -180
        type: number
    mapcodes: 
      description: "Enables the return of a comma-separted mapcodes list. Can also filter the Response to only show selected mapcode types. See <a href=\"/search-api/search-api-documentation-search/fuzzy-search#mapcodes\" target=\"_blank\">Mapcodes in the Response</a>."
      in: query
      name: mapcodes
      schema: 
        type: string
    maxFuzzyLevel: 
      description: "Maximum fuzziness level to be used."
      in: query
      name: maxFuzzyLevel
      schema: 
        default: 2
        maximum: 4
        minimum: 1
        type: integer
    maxPowerKW: 
      description: "An optional parameter which could be used to restrict the result to the Points Of Interest of type Electric Vehicle Station supporting at least one connector with a specific maximum value of power in kilowatts (closed interval - with that value)."
      in: query
      name: maxPowerKW
      schema: 
        format: double
        type: number
    minFuzzyLevel: 
      description: "Minimum fuzziness level to be used."
      in: query
      name: minFuzzyLevel
      schema: 
        default: 1
        maximum: 4
        minimum: 1
        type: integer
    minPowerKW: 
      description: "An optional parameter which could be used to restrict the result to the Points Of Interest of type Electric Vehicle Station supporting at least one connector with a specific minimal value of power in kilowatts (closed interval - with that value)."
      in: query
      name: minPowerKW
      schema: 
        format: double
        type: number
    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: 
        maximum: 1900
        type: integer
    openingHours: 
      description: "List of opening hours for a POI."
      in: query
      name: openingHours
      schema: 
        enum: 
          - nextSevenDays
        type: string
    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
    relatedPois: 
      description: "An optional parameter that provides the possibility to return related Points Of Interest."
      in: query
      name: relatedPois
      schema: 
        default: off
        enum: 
          - off
          - child
          - parent
          - all
        type: string
    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
    timeZone: 
      description: "Used to indicate the mode in which the timeZone object should be returned."
      in: query
      name: timeZone
      schema: 
        enum: 
          - iana
        type: string
    topLeft: 
      description: "Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon."
      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: 
        type: boolean
    unit:
      description: "Unit details of the address in the query."
      example: "apt 3441"
      in: query
      name: unit
      schema:
        type: string
    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
          - IL
          - IN
          - MA
          - PK
          - RU
          - TR
          - CN
        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
    404596: 
      description: "Not Found: the HTTP request method (GET, POST, etc) or path is incorrect."
    405: 
      description: "Method Not Allowed: the HTTP method (GET, POST, etc) is not supported for this request."
    429: 
      description: "Too Many Requests: Rate or volume limit exceeded"
    5xx: 
      description: "An error occurred while processing the request. Please try again later."
  securitySchemes: 
    api_key: 
      in: query
      name: key
      type: apiKey
info: 
  contact: 
    name: "Contact Us"
    url: "https://support.tomtom.com/support"
  description: >+
    The Geocoding API is a powerful tool that converts addresses, such as "109 Park Row, New York, United States," into geographic coordinates (e.g., "lat": 40.71226, "lon": -74.00207). Designed for machine-to-machine interaction, the TomTom Geocoding API is capable of handling requests from automated systems to geocode addresses that may be incomplete, incorrectly formatted, or contain typos, providing the best possible result.  

    
    It infers geographic information given a textual place description (postal address) and additional (optional) parameters that guide the search. Examples of optional parameters include a list of countries to search for and a location to search around. The main elements in the geographic information include:   

      - address components    

      - corresponding geographic coordinates    

      - a complete formatted address  

    The Geocoding API provides a simple way to make a request and obtain the desired geographic information in JSON or XML formats, depending on the user's preference. Please note that this API does not return Points of Interest (POIs).  


  title: "Geocoding API"
  version: "1.0.0"
openapi: "3.0.0"
paths: 
  ? "/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"
        - 
          $ref: "#/components/parameters/mapcodes"
        - 
          $ref: "#/components/parameters/entityTypeSet"
      responses: 
        ? "200"
        : 
          $ref: "#/components/responses/200"
        ? "400"
        : 
          $ref: "#/components/responses/400"
        ? "403"
        : 
          $ref: "#/components/responses/403"
        ? "404"
        : 
          $ref: "#/components/responses/404596"
        ? "405"
        : 
          $ref: "#/components/responses/405"
        ? "429"
        : 
          $ref: "#/components/responses/429"
        ? "596"
        : 
          $ref: "#/components/responses/404596"
        5XX: 
          $ref: "#/components/responses/5xx"
      summary: Geocode
      tags: 
        - Geocoding
  ? "/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"
        - 
          $ref: "#/components/parameters/view"
        - 
          $ref: "#/components/parameters/entityTypeSet"
      responses: 
        ? "200"
        : 
          $ref: "#/components/responses/200"
        ? "400"
        : 
          $ref: "#/components/responses/400"
        ? "403"
        : 
          $ref: "#/components/responses/403"
        ? "404"
        : 
          $ref: "#/components/responses/404596"
        ? "405"
        : 
          $ref: "#/components/responses/405"
        ? "429"
        : 
          $ref: "#/components/responses/429"
        ? "596"
        : 
          $ref: "#/components/responses/404596"
        5XX: 
          $ref: "#/components/responses/5xx"
      summary: "Structured Geocode"
      tags:
        - Geocoding
  ? "/search/{versionNumber}/premiumGeocode/{query}.{ext}"
  :
    get:
      parameters:
        -
          $ref: "#/components/parameters/versionNumber"
        -
          description: "Query string. Must be properly URL encoded."
          example: "3401 S Lamar Blvd, Austin, TX"
          in: path
          name: query
          required: true
          schema:
            type: string
        -
          $ref: "#/components/parameters/ext"
        -
          $ref: "#/components/parameters/unit"
        -
          $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"
        -
          $ref: "#/components/parameters/mapcodes"
        -
          $ref: "#/components/parameters/entityTypeSet"
      responses:
        ? "200"
        :
          $ref: "#/components/responses/200"
        ? "400"
        :
          $ref: "#/components/responses/400"
        ? "403"
        :
          $ref: "#/components/responses/403"
        ? "404"
        :
          $ref: "#/components/responses/404596"
        ? "405"
        :
          $ref: "#/components/responses/405"
        ? "429"
        :
          $ref: "#/components/responses/429"
        ? "596"
        :
          $ref: "#/components/responses/404596"
        5XX:
          $ref: "#/components/responses/5xx"
      summary: Premium Geocode
      tags:
        - Premium Geocoding
security:
  - 
    api_key: []
servers: 
  - 
    url: "https://api.tomtom.com"