{"openapi":"3.0.0","info":{"title":"Geocoding and Search API v7","version":"7.157","description":"This document describes the Geocoding and Search API.\n\n### \"ALPHA\" & \"BETA\" tags\n\n- API requests parameters and response fields can be tagged with one of the following maturity qualifiers: alpha, beta\n- \"ALPHA\" tagged features are in mid-stage development. They can change or in rare cases be removed.\n  No backward compatibility is guaranteed nor bug service level agreement (SLA) do apply.\n  Customers using ALPHA features are advised not use them in production.\n- \"BETA\" tagged features are in end-stage development. They are backward compatible and can not be removed.\n  They have no major bug, but coverage, quality, performance, or test coverage is not considered final.\n  customers can safely use BETA features in their applications if they accept those limitations and potential behavior refinements.\n\n### \"RESTRICTED\" tag\n\nAPI requests parameters and response fields can be tagged with the privilege qualifier \"RESTRICTED\".\nSuch features are only available to customers having a specific contract with HERE.\nUnauthorized usages are typically leading to a http status code 403.\n\n\n"},"security":[{"Bearer":[]},{"ApiKey":[]}],"externalDocs":{"description":"The developer guide, release notes, and migration guide are available here.","url":"https://www.here.com/docs/category/geocoding-search-v7"},"servers":[{"url":"https://autocomplete.search.hereapi.com/v1"}],"paths":{"/autocomplete":{"get":{"summary":"Autocomplete","description":"This endpoint completes entered keystrokes to a valid street address or\nadministrative area to speed-up entering address queries.","parameters":[{"$ref":"#/components/parameters/qAutocomplete"},{"$ref":"#/components/parameters/atAutocompleteGeocode"},{"$ref":"#/components/parameters/inAutocomplete"},{"$ref":"#/components/parameters/postalCodeMode"},{"$ref":"#/components/parameters/typesAutocomplete"},{"$ref":"#/components/parameters/withAutocomplete"},{"$ref":"#/components/parameters/langAutocomplete"},{"$ref":"#/components/parameters/limitAutocomplete"},{"$ref":"#/components/parameters/politicalView"},{"$ref":"#/components/parameters/showAutocomplete"},{"$ref":"#/components/parameters/X-Request-ID"}],"responses":{"200":{"description":"The search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenSearchAutocompleteResponse"}}}},"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"}}}},"429":{"description":"Client error: Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Temporary server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"qAutocomplete":{"name":"q","description":"Enter a free-text query\n\nExamples:\n * `ber`, `berl`, `berli`, ...\n * `berlin+p`, `berlin+paris`, `berlin+parise`, ...\n * `berlin+pariser+20`\n\n _Note: Whitespace, urls, email addresses, or other out-of-scope queries will yield no results._\n","in":"query","required":true,"schema":{"type":"string","example":"Berlin Pariser 20"}},"atAutocompleteGeocode":{"name":"at","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","in":"query","required":false,"schema":{"type":"string"}},"inAutocomplete":{"name":"in","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 must be provided in uppercase.\n\n   Format: `countryCode:{countryCode}[,{countryCode}]*`\n\n   Examples:\n    * `countryCode:USA`\n    * `countryCode:CAN,MEX,USA`\n\n\n * a circular area, provided as latitude, longitude, and radius (in meters)\n\n   Format: `circle:{latitude},{longitude};r={radius}`\n\n   Type: `circle:{decimal},{decimal};r={integer}`\n\n   Example: `circle:52.53,13.38;r=10000`\n\n\n * a bounding box, provided as _west longitude_, _south latitude_, _east longitude_, _north latitude_\n\n   Format: `bbox:{west longitude},{south latitude},{east longitude},{north latitude}`\n\n   Example: `bbox:13.08836,52.33812,13.761,52.6755`\n\n\nThe following constraints apply:\n\n * Parameters \"at\", \"in=circle\" and \"in=bbox\" are mutually exclusive. Only one of them is allowed.\n","in":"query","required":false,"schema":{"type":"string"}},"postalCodeMode":{"name":"postalCodeMode","description":"Options to return multiple results in areas where a postal code is associated with more than one district or city area.\nWithout these options, the system only provides one result and may leave the district or city name blank or use a default name,\npotentially omitting relevant districts of cities.\n\nDescription of supported values:\n\n- `cityLookup`: When a postal code spans multiple cities, this option gives you all possible combinations of the postal code with the corresponding city names.\n- `districtLookup`: When a postal code spans multiple districts (within one city or across multiple cities), this option gives you all possible combinations of the postal code with the corresponding district and city names.","in":"query","explode":false,"required":false,"schema":{"type":"string","enum":["cityLookup","districtLookup"]}},"typesAutocomplete":{"name":"types","description":"Limit the result items to the specified types.\n\nProvide one of the supported values or a comma separated list.\n\nDescription of supported values:\n\n- `address`: restricting results to result types `houseNumber`, `street`, `postalCodePoint`, `intersection`\n- `area`: restricting results to result types `locality` or `administrativeArea` including all the sub-types\n- `city`: restricting results to result type `locality` and locality type `city`\n- `houseNumber`: restricting results to result type: `houseNumber`, including house number types `PA` (Point Address) and `interpolated`.\n- `postalCode`: restricting results to postal codes: either result type `postalCodePoint` or result type `locality` with locality type `postalCode`.\n\n    Note that in Ireland and Singapore, where each address has unique postal code,\n    `postalCodePoint` results are replaced by `houseNumber` results.\n- `street`: restricting results to result type `street`","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["address","area","city","houseNumber","postalCode","street"]}}},"withAutocomplete":{"name":"with","description":"Activate certain features or consider specific kinds of results, that would not be active or provided by default.\n\nDescription of supported values:\n\n- **RESTRICTED** `MPA`: Enables the returning of Micro Point Address results. GS7 Autocomplete supports micro point addresses in the following countries: AUS.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["MPA"]}}},"langAutocomplete":{"name":"lang","description":"Select the preferred response language for result rendering from a list of BCP47 compliant Language Codes.\nThe Autocomplete endpoint attemps to detect the query language based on matching name variants and then chooses the same language for the response.\n\nThe end-user is able to see and recognize all the entered terms in the same language as in the query.\nThe specified preferred language is used only for unmatched address tokens and for matched address tokens in case of ambiguity\n","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string"}}},"limitAutocomplete":{"name":"limit","description":"Maximum number of results to be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":20,"default":5}},"politicalView":{"name":"politicalView","description":"Toggle the political view.\n\nThis parameter accepts a single ISO 3166-1 alpha-3 country code in all uppercase.\n\nIf a valid 3-letter country code is provided for which GS7 does not have a dedicated political view, it will fallback to the default view.\n\nThe following political views are currently supported:\n\n- `ARG`: Argentina's view on the Southern Patagonian Ice Field and Tierra Del Fuego, including the Falkland Islands, South Georgia, and South Sandwich Islands\n- `EGY`: Egypt's view on Bir Tawil\n- `IND`: India's view on Gilgit-Baltistan\n- `KEN`: Kenya's view on the Ilemi Triangle\n- `MAR`: Morocco's view on Western Sahara\n- `PAK`: Pakistan's view on Jammu and Kashmir and the Junagadh Area\n- `RUS`: Russia's view on Crimea\n- `SDN`: Sudan's view on the Halaib Triangle\n- `SRB`: Serbia's view on Kosovo, Vukovar, and Sarengrad Islands\n- `SUR`: Suriname's view on the Courantyne Headwaters and Lawa Headwaters\n- `SYR`: Syria's view on the Golan Heights\n- `TUR`: Turkey's view on Cyprus and Northern Cyprus\n- `TZA`: Tanzania's view on Lake Malawi\n- `URY`: Uruguay's view on Rincon de Artigas\n- `VNM`: Vietnam's view on the Paracel Islands and Spratly Islands","in":"query","required":false,"schema":{"type":"string"}},"showAutocomplete":{"name":"show","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 some sections there is a long and a short ID.\n\nDescription of supported values:\n\n- `streetInfo`: For each result item renders additional block with the street name decomposed into its parts like the base name, the street type, etc.\n- **ALPHA, RESTRICTED** `hasRelatedMPA`:\n  For each result of type `houseNumber` with houseNumberType `pointAddress`, render a Boolean flag indicating\n  whether sub-premises (Micro Point Addresses in HERE terms) are associated.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["hasRelatedMPA","streetInfo"]}}},"X-Request-ID":{"name":"X-Request-ID","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.","in":"header","required":false,"schema":{"type":"string"}}},"schemas":{"OpenSearchAutocompleteResponse":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AutocompleteResultItem"}]},"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."}}},"ErrorResponse":{"type":"object","required":["status","title","correlationId","requestId"],"properties":{"status":{"type":"integer","format":"int32","description":"The HTTP status code"},"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"}}},"AutocompleteResultItem":{"type":"object","required":["title","id","address"],"properties":{"title":{"type":"string","description":"The unified display name of this result item. The result title is composed so that the customer\napplication can use it to highlight parts of the suggestions. It is following a consistent schema\nfor all results, regardless of their location. The highlighting details are about the\ntitle field and each of the address fields, from the country name down to the address house number.\nIt is also built out from address components identified by the end-user, who can choose a result.\nFor example: \"Germany, 32547, Bad Oeynhausen, Schulstraße 4\""},"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."},"language":{"type":"string","description":"The preferred language of address elements in the result."},"politicalView":{"type":"string","description":"ISO3 country code of the item political view (default for international). This response element is populated when the politicalView parameter is set in the query"},"resultType":{"type":"string","enum":["administrativeArea","houseNumber","intersection","locality","postalCodePoint","street"],"description":"\nType of the result item.\n\nNote: `addressBlock` result item is either a block or subblock.\n\n`resultType` values can get added to the list without further notice.\n"},"houseNumberType":{"type":"string","enum":["MPA","PA","interpolated"],"description":"Indicates the address type which affects the precision of the address and the coordinate accuracy.\n\nDescription of supported values:\n\n- **RESTRICTED** `MPA`: A Micro Point Address represents a secondary address for a Point\n  Address; for example, building, floor (level) and suite (unit).\n  Micro Point Addresses can be used to enhance Point Address with\n  greater address detail and higher coordinate accuracy. This result\n  type is only returned by Lookup, Geocode, Autocomplete or (Multi) Reverse Geocode endpoints when\n  `with=MPA` parameter is provided.\n- `PA`: A Point Address represents an individual address as a point object.\n  Point Addresses are coming from trusted sources. There is a\n  high certainty that the address exists at that position. A\n  Point Address result contains two types of coordinates. One is the\n  access point (or navigation coordinates), which is the point to\n  start or end a drive. The other point is the position or display\n  point. This point varies per source and country. The point can be\n  the rooftop point, a point close to the building entry, or a point\n  close to the building, driveway or parking lot that belongs to the\n  building.\n- `interpolated`: An interpolated address. These are approximate positions as a\n  result of a linear interpolation based on address ranges. Address\n  ranges, especially in the USA, are typical per block. For\n  interpolated addresses, we cannot say with confidence that the\n  address exists in reality. But the interpolation provides a good\n  location approximation that brings people in most use cases close\n  to the target location. The access point of an interpolated address\n  result is calculated based on the address range and the road\n  geometry. The position (display) point is pre-configured offset\n  from the street geometry. Compared to Point Addresses, interpolated\n  addresses are less accurate."},"estimatedPointAddress":{"type":"boolean","description":"If true, indicates that the coordinates of `position` and `access` points of the Point Address are\nestimated.\nThis field is visible only for result items with resultType `houseNumber` and houseNumberType `PA` and\nonly when the value is `true`"},"localityType":{"type":"string","enum":["city","district","postalCode","subdistrict"],"description":"\nType of the locality result if the `resultType` field is set to `locality`.\n\n`localityType` values can get added to the list without further notice.\n"},"administrativeAreaType":{"type":"string","enum":["country","county","state"],"description":"\nType of the administrative area result if the `resultType` field is set to `administrativeArea`.\n\n`administrativeAreaType` values can get added to the list without further notice.\n"},"address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Detailed address of the result item."},"distance":{"type":"integer","format":"int64","description":"The distance \"as the crow flies\" from the search center to this result item in meters. For example: \"172039\".\n\nWhen searching along a route this is the distance along the route plus the distance from the route polyline to this result item.","example":172039},"highlights":{"allOf":[{"$ref":"#/components/schemas/TitleAndAddressHighlighting"}],"description":"Describes how the parts of the response element matched the input query"},"hasRelatedMPA":{"type":"boolean","description":"**ALPHA, RESTRICTED**\n\n`true`: Indicates that sub-premises (referred to as Micro Point Addresses in HERE terminology) are associated with the house number.\n\n`false`: Indicates that no sub-premises (referred to as Micro Point Addresses in HERE terminology) are associated with the house number.\n\nThis field is visible only for result items with resultType `houseNumber` and houseNumberType `PA`.\n\nThe field is rendered only if `show=hasRelatedMPA` is provided.\n"},"streetInfo":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/StreetInfo"}]},"description":"Street Details (only rendered if `show=streetInfo` is provided.)"}}},"Address":{"type":"object","properties":{"label":{"type":"string","description":"Assembled address value built out of the address components according to the regional postal rules.\nThese are the same rules for all endpoints. It may not include all the input terms. For example:\n\"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\""},"streets":{"type":"array","items":{"type":"string"},"description":"Names of streets in case of intersection result. For example: [\"Friedrichstraße\",\"Unter den Linden\"]"},"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\""},"building":{"type":"string","description":"Name of building."},"unit":{"type":"string","description":"Secondary unit information. It may include building, floor (level), and suite (unit) details. This field is returned by Geocode, Autocomplete, (Multi) Reverse Geocode and Lookup endpoints only."}}},"TitleAndAddressHighlighting":{"type":"object","properties":{"title":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Ranges of indexes that matched in the title attribute"},"address":{"allOf":[{"$ref":"#/components/schemas/AddressHighlightingInformation"}],"description":"Ranges of indexes that matched in the individual address attributes"}}},"StreetInfo":{"type":"object","properties":{"baseName":{"type":"string","description":"Base name part of the street name."},"streetType":{"type":"string","description":"Street type part of the street name."},"streetTypePrecedes":{"type":"boolean","description":"Defines if the street type is before or after the base name."},"streetTypeAttached":{"type":"boolean","description":"Defines if the street type is attached or unattached to the base name."},"prefix":{"type":"string","description":"A prefix is a directional identifier that precedes, but is not included in, the base name of a road."},"suffix":{"type":"string","description":"A suffix is a directional identifier that follows, but is not included in, the base name of a road."},"direction":{"type":"string","description":"Indicates the official directional identifiers assigned to highways, typically either \"North/South\" or \"East/West\""},"language":{"type":"string","description":"BCP 47 compliant language code"}}},"Range":{"type":"object","required":["start","end"],"properties":{"start":{"type":"integer","format":"int32","description":"first index of the matched range (0-based indexing, inclusive)"},"end":{"type":"integer","format":"int32","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"}}},"AddressHighlightingInformation":{"type":"object","properties":{"label":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the address label."},"country":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Country field."},"countryCode":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Country Code field."},"state":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the State field."},"stateCode":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the State Code field."},"county":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the County field."},"countyCode":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the County Code field."},"city":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the City field."},"district":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the District field."},"subdistrict":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Sub-District field."},"block":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Block field."},"subblock":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Sub-Block field."},"street":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Street field."},"streets":{"type":"array","items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]}},"description":"Indicates matched substrings in the Streets field."},"postalCode":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Postal Code field."},"houseNumber":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the House Number field."},"building":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"Indicates matched substrings in the Building field."},"unit":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Range"}]},"description":"**RESTRICTED**\n\nIndicates matched substrings in the unit field for Micro Point Address results. This result type is only returned when `with=MPA` parameter is provided. This field is returned by Autocomplete endpoint only."}}}},"securitySchemes":{"Bearer":{"description":"A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\nFor more information on how to get a bearer token, see the\n[Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/).\n","type":"http","scheme":"bearer","bearerFormat":"JWT"},"ApiKey":{"description":"A key generated specifically to authenticate API requests.\nFor more information on how to get an API key, see the\n[Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/).\n","type":"apiKey","name":"apiKey","in":"query"}}}}