---
updatedAt: 2026-04-17T04:51:14.000Z
agentTools:
  projectIndex: https://docs.company.info/llms.txt
---

# Geocode

This endpoint allows to find the geo-coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It also returns a complete postal address string and address details. It supports structured, unstructured and hybrid queries - combinations of structured and unstructured query elements.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Geocoding and Search API",
    "description": "This document describes the Geocoding and Search API.",
    "version": "2",
    "x-document-meta-data": {
      "copyright": "© 2021 Company.info B.V."
    }
  },
  "servers": [
    {
      "url": "https://api.company.info/routeplanner/search",
      "description": "Production server for the RoutePlanner GEO Service"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "x-readme": {
    "proxy-enabled": false
  },
  "paths": {
    "/geocode": {
      "get": {
        "operationId": "getGeoCode",
        "summary": "Geocode",
        "tags": [
          "Search"
        ],
        "description": "This endpoint allows to find the geo-coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It also returns a complete postal address string and address details. It supports structured, unstructured and hybrid queries - combinations of structured and unstructured query elements.",
        "parameters": [
          {
            "name": "at",
            "in": "query",
            "description": "Specify the center of the search context expressed as coordinates.\n\nFormat: `{latitude},{longitude}`\n\nType: `{decimal},{decimal}`\n\nExample: `-13.163068,-72.545128` (Machu Picchu Mountain, Peru)\n",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "in",
            "in": "query",
            "description": "Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified area.\n\nA geographic area can be\n\n * a country (or multiple countries), provided as comma-separated [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country codes\n\n   The country codes are to be provided in all uppercase.\n\n   Format: `countryCode:{countryCode}[,{countryCode}]*`\n\n   Examples:\n    * `countryCode:USA`\n    * `countryCode:CAN,MEX,USA`\n\n",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to be returned.",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer",
              "format": "int32",
              "default": 20
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Enter a free-text query\n\nExamples:\n * `125, Berliner, berlin`\n * `Beacon, Boston, Hospital`\n * `Schnurrbart German Pub and Restaurant, Hong Kong`\n\n_Note: Either `q` or `qq`-parameter is required on this endpoint. Both parameters can be provided in the same request._\n",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "Invalidenstraße 116 Berlin"
            }
          },
          {
            "name": "qq",
            "in": "query",
            "description": "Enter a qualified query. A qualified query is similar to a free-text query, but in a structured manner.\n It can take multiple _sub-parameters_, separated by semicolon, allowing to specify different aspects of a query.\n\nCurrently supported _sub-parameters_ are `country`, `state`, `county`, `city`, `district`, `street`,\n `houseNumber`, and `postalCode`.\n\nFormat: `{sub-parameter}={string}[;{sub-parameter}={string}]*`\n\nExamples:\n * `city=Berlin;country=Germany;street=Friedrichstr;houseNumber=20`\n * `city=Berlin;country=Germany`\n * `postalCode=10969`\n\n_Note: Either `q` or `qq`-parameter is required on this endpoint. Both parameters can be provided in the same request._\n",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Select the language to be used for result rendering from a list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes.",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show",
            "in": "query",
            "description": "Select additional fields to be rendered in the response.\nPlease note that some of the fields involve additional webservice calls and can increase the overall response time.\n\nThe value is a comma-separated list of the sections to be enabled.\nFor each section there is a long and a short version of its id.\n\nDescription of accepted values:\n\nBETA: 'parsing'",
            "required": false,
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "parsing"
                ]
              }
            }
          },
          {
            "name": "X-Request-ID",
            "in": "header",
            "description": "Used to correlate requests with their responses within a customer's application, for logging and error reporting.\n\nFormat: Free string, but a valid UUIDv4 is recommended.",
            "required": false,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenSearchGeocodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Client error: request failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Client error: http method not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Temporary server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OpenSearchGeocodeResponse": {
        "required": [
          "items"
        ],
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "description": "The results are presented as a JSON list of candidates in ranked order (most-likely to least-likely) based on the matched location criteria.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/GeocodeResultItem"
                }
              ]
            }
          }
        }
      },
      "GeocodeResultItem": {
        "required": [
          "address",
          "title"
        ],
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "The localized display name of this result item."
          },
          "id": {
            "type": "string",
            "description": "The unique identifier for the result item. This ID can be used for a Look Up by ID search as well."
          },
          "resultType": {
            "type": "string",
            "description": "WARNING: The resultType values 'intersection' and 'postalCodePoint' are in BETA state",
            "enum": [
              "administrativeArea",
              "locality",
              "street",
              "intersection",
              "addressBlock",
              "houseNumber",
              "postalCodePoint",
              "place"
            ]
          },
          "houseNumberType": {
            "type": "string",
            "enum": [
              "PA",
              "interpolated"
            ]
          },
          "addressBlockType": {
            "type": "string",
            "enum": [
              "block",
              "subblock"
            ]
          },
          "localityType": {
            "type": "string",
            "enum": [
              "postalCode",
              "subdistrict",
              "district",
              "city"
            ]
          },
          "administrativeAreaType": {
            "type": "string",
            "enum": [
              "county",
              "state",
              "country"
            ]
          },
          "address": {
            "description": "Postal address of the result item.",
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ]
          },
          "position": {
            "description": "The coordinates (latitude, longitude) of a pin on a map corresponding to the searched place.",
            "allOf": [
              {
                "$ref": "#/components/schemas/DisplayResponseCoordinate"
              }
            ]
          },
          "access": {
            "type": "array",
            "description": "Coordinates of the place you are navigating to (for example, driving or walking). This is a point on a road or in a parking lot.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/AccessResponseCoordinate"
                }
              ]
            }
          },
          "distance": {
            "type": "integer",
            "description": "The distance from the search center to this result item in meters. For example: \"172039\"",
            "format": "int64"
          },
          "mapView": {
            "description": "The bounding box enclosing the geometric shape (area or line) that an individual result covers. `place` typed results have no `mapView`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MapView"
              }
            ]
          },
          "categories": {
            "type": "array",
            "description": "The list of categories assigned to this place.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Category"
                }
              ]
            }
          },
          "foodTypes": {
            "type": "array",
            "description": "The list of food types assigned to this place.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Category"
                }
              ]
            }
          },
          "houseNumberFallback": {
            "type": "boolean",
            "description": "If true, indicates that the requested house number was corrected to match the nearest known house number. This field is visible only when the value is true."
          },
          "scoring": {
            "description": "Indicates for each result how good the result matches to the original query. This can be used by the customer application to accept or reject the results depending on how \"expensive\" is the mistake for their use case",
            "allOf": [
              {
                "$ref": "#/components/schemas/Scoring"
              }
            ]
          },
          "parsing": {
            "description": "BETA - Parsed terms and their positions in the input query (only rendered if 'show=parsing' is provided.)",
            "allOf": [
              {
                "$ref": "#/components/schemas/Parsing"
              }
            ]
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Assembled address value built out of the address components according to the regional postal rules. These are the same rules for all endpoints. It may not include all the input terms. For example: \"Schulstraße 4, 32547 Bad Oeynhausen, Germany\""
          },
          "countryCode": {
            "type": "string",
            "description": "A three-letter country code. For example: \"DEU\""
          },
          "countryName": {
            "type": "string",
            "description": "The localised country name. For example: \"Deutschland\""
          },
          "stateCode": {
            "type": "string",
            "description": "A state code or state name abbreviation – country specific. For example, in the United States it is the two letter state abbreviation: \"CA\" for California."
          },
          "state": {
            "type": "string",
            "description": "The state division of a country. For example: \"North Rhine-Westphalia\""
          },
          "countyCode": {
            "type": "string",
            "description": "A county code or county name abbreviation – country specific. For example, for Italy it is the province abbreviation: \"RM\" for Rome."
          },
          "county": {
            "type": "string",
            "description": "A division of a state; typically, a secondary-level administrative division of a country or equivalent."
          },
          "city": {
            "type": "string",
            "description": "The name of the primary locality of the place. For example: \"Bad Oyenhausen\""
          },
          "district": {
            "type": "string",
            "description": "A division of city; typically an administrative unit within a larger city or a customary name of a city's neighborhood. For example: \"Bad Oyenhausen\""
          },
          "subdistrict": {
            "type": "string",
            "description": "A subdivision of a district. For example: \"Minden-Lübbecke\""
          },
          "street": {
            "type": "string",
            "description": "Name of street. For example: \"Schulstrasse\""
          },
          "block": {
            "type": "string",
            "description": "Name of block."
          },
          "subblock": {
            "type": "string",
            "description": "Name of sub-block."
          },
          "postalCode": {
            "type": "string",
            "description": "An alphanumeric string included in a postal address to facilitate mail sorting, such as post code, postcode, or ZIP code. For example: \"32547\""
          },
          "houseNumber": {
            "type": "string",
            "description": "House number. For example: \"4\""
          }
        }
      },
      "DisplayResponseCoordinate": {
        "required": [
          "lat",
          "lng"
        ],
        "type": "object",
        "properties": {
          "lat": {
            "type": "number",
            "description": "Latitude of the address. For example: \"52.19404\"",
            "format": "double"
          },
          "lng": {
            "type": "number",
            "description": "Longitude of the address. For example: \"8.80135\"",
            "format": "double"
          }
        }
      },
      "AccessResponseCoordinate": {
        "required": [
          "lat",
          "lng"
        ],
        "type": "object",
        "properties": {
          "lat": {
            "type": "number",
            "description": "Latitude of the address. For example: \"52.19404\"",
            "format": "double"
          },
          "lng": {
            "type": "number",
            "description": "Longitude of the address. For example: \"8.80135\"",
            "format": "double"
          }
        }
      },
      "MapView": {
        "required": [
          "east",
          "north",
          "south",
          "west"
        ],
        "type": "object",
        "properties": {
          "west": {
            "type": "number",
            "description": "Longitude of the western-side of the box. For example: \"8.80068\"",
            "format": "double"
          },
          "south": {
            "type": "number",
            "description": "Latitude of the southern-side of the box. For example: \"52.19333\"",
            "format": "double"
          },
          "east": {
            "type": "number",
            "description": "Longitude of the eastern-side of the box. For example: \"8.8167\"",
            "format": "double"
          },
          "north": {
            "type": "number",
            "description": "Latitude of the northern-side of the box. For example: \"52.19555\"",
            "format": "double"
          }
        }
      },
      "Category": {
        "required": [
          "id"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier number for an associated category. For example: \"900-9300-0000\""
          },
          "name": {
            "type": "string",
            "description": "Name of the place category in the result item language."
          },
          "primary": {
            "type": "boolean",
            "description": "Whether or not it is a primary category. This field is visible only when the value is 'true'."
          }
        }
      },
      "Scoring": {
        "type": "object",
        "properties": {
          "queryScore": {
            "type": "number",
            "description": "Indicates how good the input matches the returned address. It is equal to 1 if all input tokens are recognized and matched.",
            "format": "double"
          },
          "fieldScore": {
            "description": "Indicates how good the individual result fields match to the corresponding part of the query. Is included only for the result fields that are actually matched to the query.",
            "allOf": [
              {
                "$ref": "#/components/schemas/FieldScore"
              }
            ]
          }
        }
      },
      "FieldScore": {
        "type": "object",
        "properties": {
          "country": {
            "type": "number",
            "description": "Indicates how good the result country name or [ISO 3166-1 alpha-3] country code matches to the freeform or qualified input.",
            "format": "double"
          },
          "countryCode": {
            "type": "number",
            "description": "Indicates how good the result [ISO 3166-1 alpha-3] country code matches to the freeform or qualified input.",
            "format": "double"
          },
          "state": {
            "type": "number",
            "description": "Indicates how good the result state name matches to the freeform or qualified input.",
            "format": "double"
          },
          "stateCode": {
            "type": "number",
            "description": "Indicates how good the result state code matches to the freeform or qualified input.",
            "format": "double"
          },
          "county": {
            "type": "number",
            "description": "Indicates how good the result county name matches to the freeform or qualified input.",
            "format": "double"
          },
          "countyCode": {
            "type": "number",
            "description": "Indicates how good the result county code matches to the freeform or qualified input.",
            "format": "double"
          },
          "city": {
            "type": "number",
            "description": "Indicates how good the result city name matches to the freeform or qualified input.",
            "format": "double"
          },
          "district": {
            "type": "number",
            "description": "Indicates how good the result district name matches to the freeform or qualified input.",
            "format": "double"
          },
          "subdistrict": {
            "type": "number",
            "description": "Indicates how good the result sub-district name matches to the freeform or qualified input.",
            "format": "double"
          },
          "streets": {
            "type": "array",
            "description": "Indicates how good the result street names match to the freeform or qualified input. If the input contains multiple street names, the field score is calculated and returned for each of them individually.",
            "items": {
              "type": "number",
              "format": "double"
            }
          },
          "block": {
            "type": "number",
            "description": "Indicates how good the result block name matches to the freeform or qualified input.",
            "format": "double"
          },
          "subblock": {
            "type": "number",
            "description": "Indicates how good the result sub-block name matches to the freeform or qualified input.",
            "format": "double"
          },
          "houseNumber": {
            "type": "number",
            "description": "Indicates how good the result house number matches to the freeform or qualified input. It may happen, that the house number, which one is looking for, is not yet in the map data. For such cases, the /geocode returns the nearest known house number on the same street. This represents the numeric difference between the requested and the returned house numbers.",
            "format": "double"
          },
          "postalCode": {
            "type": "number",
            "description": "Indicates how good the result postal code matches to the freeform or qualified input.",
            "format": "double"
          },
          "building": {
            "type": "number",
            "description": "Indicates how good the result building name matches to the freeform or qualified input.",
            "format": "double"
          },
          "unit": {
            "type": "number",
            "description": "Indicates how good the result unit (such as a micro point address) matches to the freeform or qualified input.",
            "format": "double"
          },
          "placeName": {
            "type": "number",
            "description": "Indicates how good the result place name matches to the freeform or qualified input.",
            "format": "double"
          },
          "ontologyName": {
            "type": "number",
            "description": "Indicates how good the result ontology name matches to the freeform or qualified input.",
            "format": "double"
          }
        }
      },
      "Parsing": {
        "type": "object",
        "properties": {
          "placeName": {
            "type": "array",
            "description": "Place name matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "country": {
            "type": "array",
            "description": "Country matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "state": {
            "type": "array",
            "description": "State matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "county": {
            "type": "array",
            "description": "County matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "city": {
            "type": "array",
            "description": "City matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "district": {
            "type": "array",
            "description": "District matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "subdistrict": {
            "type": "array",
            "description": "Subdistrict matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "street": {
            "type": "array",
            "description": "Street matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "block": {
            "type": "array",
            "description": "Block matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "subblock": {
            "type": "array",
            "description": "Subblock matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "houseNumber": {
            "type": "array",
            "description": "HouseNumber matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "postalCode": {
            "type": "array",
            "description": "PostalCode matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "building": {
            "type": "array",
            "description": "Building matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "secondaryUnits": {
            "type": "array",
            "description": "secondaryUnits matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          },
          "ontologyName": {
            "type": "array",
            "description": "Ontology name matches",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MatchInfo"
                }
              ]
            }
          }
        }
      },
      "MatchInfo": {
        "required": [
          "end",
          "start",
          "value"
        ],
        "type": "object",
        "properties": {
          "start": {
            "type": "integer",
            "description": "First index of the matched range (0-based indexing, inclusive)",
            "format": "int32"
          },
          "end": {
            "type": "integer",
            "description": "One past the last index of the matched range (0-based indexing, exclusive); The difference between end and start gives the length of the term",
            "format": "int32"
          },
          "value": {
            "type": "string",
            "description": "Matched term in the input string"
          },
          "qq": {
            "type": "string",
            "description": "The matched qualified query field type. If this is not returned, then matched value refers to the freetext query",
            "enum": [
              "country",
              "state",
              "county",
              "city",
              "district",
              "street",
              "houseNumber",
              "postalCode"
            ]
          }
        }
      },
      "ErrorResponse": {
        "required": [
          "correlationId",
          "requestId",
          "status",
          "title"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32"
          },
          "title": {
            "type": "string",
            "description": "Human-readable error description"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          },
          "cause": {
            "type": "string",
            "description": "Human-readable explanation for the error"
          },
          "action": {
            "type": "string",
            "description": "Human-readable action for the user"
          },
          "correlationId": {
            "type": "string",
            "description": "Auto-generated ID univocally identifying this request"
          },
          "requestId": {
            "type": "string",
            "description": "Request identifier provided by the user"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "description": "API key used to authorize requests.\n",
        "name": "X-API-Key",
        "in": "header"
      }
    }
  }
}
```