{"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://multi-revgeocode.search.hereapi.com/v1"}],"paths":{"/multi-revgeocode":{"post":{"summary":"Multi-Reverse Geocode","description":"This endpoint returns addresses/places for a list of geo-coordinates specified in the request.","parameters":[{"$ref":"#/components/parameters/addressNamesVariantLookupRevgeocode"},{"$ref":"#/components/parameters/typesRevgeocode"},{"$ref":"#/components/parameters/withRevgeocode"},{"$ref":"#/components/parameters/langAutosuggestBrowseDiscoverGeocodeLookupRevgeocode"},{"$ref":"#/components/parameters/limitMultiRevgeocode"},{"$ref":"#/components/parameters/politicalView"},{"$ref":"#/components/parameters/showMapReferencesGeocodeLookupRevgeocode"},{"$ref":"#/components/parameters/showNavAttributes"},{"$ref":"#/components/parameters/showRelatedRevgeocode"},{"$ref":"#/components/parameters/showRevgeocode"},{"$ref":"#/components/parameters/X-Request-ID"}],"responses":{"200":{"description":"The search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenSearchMultiReverseGeocodeResponse"}}}},"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"}}}},"413":{"description":"Client error: request body exceeds size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Client error: request body has unsupported content type.","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"}}}}},"requestBody":{"description":"Takes a newline-separated list of requests, following the URL query parameter syntax. Each line can only contain the following parameters.\n\n* The mandatory `id` parameter to identify the sub-request. Its value must be unique per request, with a size limit of 64 characters and\n  can only contain alphanumeric characters, underscores, or dashes.\n\n  If sub-requests in the HTTP body contain same IDs, the system processes only the first occurrence and ignores the rest.\n\n* A mandatory location context: either `at` or `in:circle` must be specified, but not both at the same time.\n  The supported values are the same as for their query parameter counterparts in the Reverse Geocode endpoint.\n\n* An optional `bearing` parameter, to expresses the direction in which an asset is heading in degrees starting at true north and continuing clockwise around the compass.\n  North is 0 degrees, east is 90 degrees, south is 180 degrees, and west is 270 degrees. Values are expected to be of type Integer.\n\n  For additional constraints related to the `bearing` parameter, see the parameter description in the Reverse Geocode endpoint.\n\nNo other parameters are allowed in the body. The body parameters must not be used in the URL.\nOther request parameters can be used in the URL as specified in the corresponding section.\nThese are active for all sub-requests and combined with the location context from a body line, build a complete sub-request.\nNote that Multi-Reverse Geocode requests can only use `limit`-parameter values of up to ten. It is recommended to keep the value as low as possible for good performance.\n\nAt most, one hundred sub-requests are allowed per Multi Reverse Geocode request.\n","required":true,"content":{"text/plain; charset=UTF-8":{"schema":{"type":"string"},"example":"id=1&at=52.4,13.4\nid=2&at=52.3,13.4"},"application/x-www-form-urlencoded":{"schema":{"type":"string"},"example":"id=1&at=52.4,13.4\nid=2&at=52.3,13.4"}}}}}},"components":{"parameters":{"addressNamesVariantLookupRevgeocode":{"name":"addressNamesVariant","description":"The deep‑object parameter enables the API to return different variants of the component names in the GS7 results.","in":"query","explode":true,"style":"deepObject","required":false,"schema":{"type":"object","properties":{"city":{"type":"string","enum":["administrative"],"description":"Example:\n\n`addressNamesVariant[city]=administrative`\n\n\nDescription of supported values:\n\n- `administrative`: Returns the administrative name for the selected component in the address result. This option is currently supported **only in the USA**."}}}},"typesRevgeocode":{"name":"types","description":"Limit the result items to the specified types.\n\nProvide one of the supported values or a comma separated list.\n\nThe following constraints apply:\n\n* If a `bearing` parameter is provided, the `types` parameter will accept `types=street` only.\n\n\nDescription of supported values:\n\n- `address`: restricting results to result types `houseNumber`, `street`, `postalCodePoint`, or `addressBlock`.\n  Result type \"intersection\" is excluded from this list because it is not supported in reverse geocoder.\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\n  `PA` (Point Address), `MPA` (Micro Point Address) and `interpolated`.\n- `place`: restricting results to result type `place`\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","place","street"]}}},"withRevgeocode":{"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 supports micro point addresses in the following countries: AUS, AUT, BRA, CAN, NZL, USA (with the territory of PRI).\n- `unnamedStreets`: Enables the retrieval of unnamed street results.\n- **ALPHA** `estimatedAreaFallback`: Adds district and city names to results in areas where the respective names cannot be obtained from area polygon data.\n  Instead, the Reverse Geocoder estimates these names based on administrative assignments to streets.\n  A flag “`estimatedAreaFallback: true`” is returned in response which indicates the administrative result is estimated.\n  'Distance' is calculated from the input to the closest street section, user could judge the result confidence from the distance.\n  While this estimation can be helpful in many cases, it may not always be completely accurate.\n  The probability of false results, such as neighboring district or city names, exists primarily in border regions.\n  This means that when streets are near the border between different administrative districts or cities,\n  the estimation may occasionally provide the wrong district or city name.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["MPA","estimatedAreaFallback","unnamedStreets"]}}},"langAutosuggestBrowseDiscoverGeocodeLookupRevgeocode":{"name":"lang","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.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string"}}},"limitMultiRevgeocode":{"name":"limit","description":"Maximum number of results to be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":10,"default":1}},"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"}},"showMapReferencesGeocodeLookupRevgeocode":{"name":"showMapReferences","description":"Return the map references of the location objects\n\nDescription of supported values:\n\n- `adminIds`: Return the ids for the admin hierarchy of the response, to enable cross referencing into other services or data applications based on HERE Map Content\n- `cmVersion`: Return the core map version number of the region where the result is located\n- `links`: Return the link references from the result's access position,\n  to enable cross referencing into other services or data applications\n- **RESTRICTED** `microPointAddress`: Return the reference of the micro point address,\n  to enable cross referencing into other services or data applications\n  based on HERE Map Content. This type of reference is only returned by Lookup endpoint or Geocode endpoint.\n- `pointAddress`: Return the reference of the point address,\n  to enable cross referencing into other services or data applications\n  based on HERE Map Content\n- `segments`: Return the street segment references from the result's access position,\n  to enable cross referencing into other services or data applications\n  based on HERE Map Content\n\n    **NOTE** The previous parameter `show=hmcReference` is deprecated and replaced\n    by `showMapReferences=segments` which serves the same purpose.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["adminIds","cmVersion","links","microPointAddress","pointAddress","segments"]}}},"showNavAttributes":{"name":"showNavAttributes","description":"Return requested additional attributes for segments in a road network if `showNavAttributes` parameter is specified with valid value and relevant data is available.\n\nThe value is a comma-separated list of the sections to be enabled.\n\nDescription of supported values:\n\n- `access`: Return the vehicle types allowed on a road or lane.\n- `functionalClass`: Return the functional class which is used to classify roads depending on the speed, importance and connectivity of the road.\n- `physical`: Return the values to describe special physical characteristics of a road.\n- `speedLimits`: Include speed limit and travel direction of the road in the results where available in content and when requested by the client application.\n\n  Note on `speedLimits`:\n  - The feature is not supported in Japan.\n  - This feature is subject to premium pricing. For details, contact your HERE customer representative.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["access","functionalClass","physical","speedLimits"]}}},"showRelatedRevgeocode":{"name":"showRelated","description":"allows enriching some types of response items with related items\n\nDescription of supported values:\n\n- `intersections`: For street and house number results, include a block containing a list of intersections nearest to the address.\n- `nearbyAddress`: Add nearby address as additional reference to the street level results in Reverse Geocode or Multi-Reverse Geocode, the feature is only available with parameter `bearing` or `types=street`.\n- **RESTRICTED** `parentPA`: For `type=houseNumber` and `houseNumberType=MPA` result items, include a block containing the \"parent\" point addresses associated with this micro point address. GS7 supports micro point addresses in the following countries: AUS, AUT, BRA, CAN, NZL, USA (with the territory of PRI).","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["intersections","nearbyAddress","parentPA"]}}},"showRevgeocode":{"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- `countryInfo`: For each result item renders additional block with the country info, such as\n  [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and\n  [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.\n- `postalCodeDetails`: For each result item of types `postalCodePoint` renders block with additional information about this postal code,\n  such as postal code type: ZIP or ZIP+4; ZIP classification code: PO BOX, Unique or military; record type code for ZIP+4 codes.\n  This feature is currently available only in the countries which are using ZIP codes - USA, PRI, VIR, GUM, MNP and ASM.\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- `tz`: Renders result items with additional time zone information.\n- **ALPHA, RESTRICTED** `addressUsage`: For each result item with `types=houseNumber` and `houseNumberType=pointAddress`, returns a flag indicating whether the address is residential.","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["addressUsage","countryInfo","postalCodeDetails","streetInfo","tz"]}}},"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":{"OpenSearchMultiReverseGeocodeResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/OpenSearchMultiReverseGeocodeErrorResult"},{"$ref":"#/components/schemas/OpenSearchMultiReverseGeocodeResponseItem"}]},"description":"The results for the individual queries which either contain items or an error description"}}},"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"}}},"OpenSearchMultiReverseGeocodeErrorResult":{"type":"object","required":["id","error"],"properties":{"id":{"type":"string","description":"The ID for the query provided by the client"},"error":{"allOf":[{"$ref":"#/components/schemas/MultiResultErrorSection"}],"description":"Error information"}}},"OpenSearchMultiReverseGeocodeResponseItem":{"type":"object","required":["id","items"],"properties":{"id":{"type":"string","description":"The ID for the query provided by the client"},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ReverseGeocodeResultItem"}]},"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."}}},"MultiResultErrorSection":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Human-readable error description"}}},"ReverseGeocodeResultItem":{"type":"object","required":["title","id","address"],"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."},"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":["addressBlock","administrativeArea","houseNumber","locality","place","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."},"addressUsage":{"allOf":[{"$ref":"#/components/schemas/AddressUsage"}],"description":"**ALPHA, RESTRICTED**"},"addressBlockType":{"type":"string","enum":["block","subblock"],"description":"\nType of the address block result if the `resultType` field is set to `addressBlock`.\n\n`addressBlockType` values can get added to the list without further notice.\n"},"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/RgcAddress"}],"description":"Postal address of the result item."},"postalCodeDetails":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/PostalCodeDetails_Usps_Zip"},{"$ref":"#/components/schemas/PostalCodeDetails_Usps_ZipPlus4"}]},"description":"Additional information for `postalCodePoint` results (only rendered if `show=postalCodeDetails` is\nprovided and only in the countries which are using ZIP codes - USA, PRI, VIR, GUM, MNP, ASM and JPN)"},"position":{"allOf":[{"$ref":"#/components/schemas/DisplayResponseCoordinate"}],"description":"The coordinates (latitude, longitude) of a pin on a map corresponding to the searched place."},"access":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/BasicAccessPoint"}]},"description":"Coordinates of the response item on a HERE map navigable link (for example, for driving or walking)."},"distance":{"type":"integer","format":"int64","description":"The distance \"as the crow flies\" from the search center to this result item in meters.\nFor example: \"172039\"","example":172039},"mapView":{"allOf":[{"$ref":"#/components/schemas/MapView"}],"description":"The bounding box enclosing the geometric shape (area or line) that an individual result covers. `place` typed results have no `mapView`."},"categories":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Category"}]},"description":"The list of categories assigned to this place."},"foodTypes":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Category"}]},"description":"The list of food types assigned to this place."},"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."},"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`"},"timeZone":{"allOf":[{"$ref":"#/components/schemas/TimeZoneInfo"}],"description":"Provides time zone information for this place. (rendered only if `show=tz` is provided.)"},"streetInfo":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/StreetInfo"}]},"description":"Street Details (only rendered if `show=streetInfo` is provided.)"},"countryInfo":{"allOf":[{"$ref":"#/components/schemas/CountryInfo"}],"description":"Country Details (only rendered if `show=countryInfo` is provided.)"},"estimatedAreaFallback":{"type":"boolean","description":"**ALPHA**\n\nIndicates that the admin result is not retrieved from a carto shape but from the closest street.\n(Only rendered, if `with=estimatedAreaFallback` is provided.)"},"mapReferences":{"allOf":[{"$ref":"#/components/schemas/MapReferenceSection"}],"description":"Return the map references of the location objects."},"related":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/RelatedAddress"}]},"description":"List of related objects"},"navigationAttributes":{"allOf":[{"$ref":"#/components/schemas/NavigationAttributes"}],"description":"Return requested additional attributes for segments in a road network if `showNavAttributes` parameter\nis specified with valid value and relevant data is available. The value is a comma-separated list\nof the sections to be enabled."}}},"AddressUsage":{"type":"object","required":["usageType"],"properties":{"usageType":{"type":"string","enum":["nonResidential","residential"],"description":"A flag specifying whether the address is residential. (only rendered if `show=addressUsage` is provided.)"}}},"RgcAddress":{"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\""},"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."}}},"PostalCodeDetails_Usps_Zip":{"type":"object","required":["postalCode"],"properties":{"postalCode":{"type":"string","description":"The postal code."},"postalEntity":{"type":"string","enum":["USPS"],"description":"The postal entity. This could be a governmental authority, a regulatory authority, or a designated postal operator.\n\nDescription of supported values:\n\n- `USPS`: The USPS postal code system."},"postalCodeType":{"type":"string","enum":["ZIP"],"description":"The postal code type. Currently supported values: `ZIP` and `ZIP+4`\n\nDescription of supported values:\n\n- `ZIP`: A 5-digit code that identifies a specific geographic delivery area. ZIP codes can represent an area within a state, or a single building or company that has a very high mail volume."},"zipClassificationCode":{"type":"string","enum":["M","P","U"],"description":"The ZIP Classification Code.\n\nDescription of supported values:\n\n- `M`: Military ZIP code.\n- `P`: ZIP code having only Post Office boxes.\n- `U`: Unique ZIP code: A ZIP assigned to a company, agency, or entity with sufficient mail volume, based on average daily volume of letter-size pieces."}}},"PostalCodeDetails_Usps_ZipPlus4":{"type":"object","required":["postalCode"],"properties":{"postalCode":{"type":"string","description":"The postal code."},"postalEntity":{"type":"string","enum":["USPS"],"description":"The postal entity. This could be a governmental authority, a regulatory authority, or a designated postal operator.\n\nDescription of supported values:\n\n- `USPS`: The USPS postal code system."},"postalCodeType":{"type":"string","enum":["ZIP+4"],"description":"The postal code type. Currently supported values: `ZIP` and `ZIP+4`\n\nDescription of supported values:\n\n- `ZIP+4`: Nine-digit code that identifies a small geographic delivery area that is serviceable by a single carrier; appears in the last line of the address on a mail piece."},"recordTypeCode":{"type":"string","enum":["F","G","H","P","R","S"],"description":"The USPS ZIP+4 Record Type Code.\n\nDescription of supported values:\n\n- `F`: Firm\n- `G`: General delivery\n- `H`: High-rise\n- `P`: PO Box\n- `R`: Rural route/contract\n- `S`: Street"}}},"DisplayResponseCoordinate":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","format":"double","description":"Latitude of the address. For example: `\"52.19404\"`"},"lng":{"type":"number","format":"double","description":"Longitude of the address. For example: `\"8.80135\"`"}}},"BasicAccessPoint":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","format":"double","description":"Latitude of the address. For example: `\"52.19404\"`"},"lng":{"type":"number","format":"double","description":"Longitude of the address. For example: `\"8.80135\"`"}}},"MapView":{"type":"object","required":["west","south","east","north"],"properties":{"west":{"type":"number","format":"double","description":"Longitude of the western-side of the box. For example: \"8.80068\""},"south":{"type":"number","format":"double","description":"Latitude of the southern-side of the box. For example: \"52.19333\""},"east":{"type":"number","format":"double","description":"Longitude of the eastern-side of the box. For example: \"8.8167\""},"north":{"type":"number","format":"double","description":"Latitude of the northern-side of the box. For example: \"52.19555\""}}},"Category":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Identifier number for an associated category. For example: `\"600-6600-0082\"`"},"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`."}}},"TimeZoneInfo":{"type":"object","required":["name","utcOffset"],"properties":{"name":{"type":"string","description":"The name of the time zone as defined in the [tz database](https://en.wikipedia.org/wiki/Tz_database). For example: \"Europe/Berlin\""},"utcOffset":{"type":"string","description":"The UTC offset for this time zone at request time. For example \"+02:00\""}}},"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"}}},"CountryInfo":{"type":"object","properties":{"alpha2":{"type":"string","description":"[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code"},"alpha3":{"type":"string","description":"[ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code"}}},"MapReferenceSection":{"type":"object","properties":{"links":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/LinkInfoSection"}]},"description":"An identifier for link and the side of link the attribute is applicable to"},"pointAddress":{"allOf":[{"$ref":"#/components/schemas/PointAddressSection"}],"description":"The section containing the point address reference"},"microPointAddress":{"allOf":[{"$ref":"#/components/schemas/MicroPointAddressSection"}],"description":"**RESTRICTED**\n\nThe section containing the micro point address reference. This type of reference is only returned by Lookup endpoint or Geocode endpoint when showMapReference='microPointAddress' parameter is provided."},"segments":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Segment"}]},"description":"The section containing the segment references"},"country":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"country ID in HERE Map Content"},"state":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"state ID in HERE Map Content"},"county":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"county ID in HERE Map Content"},"city":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"city ID in HERE Map Content"},"district":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"district ID in HERE Map Content"},"subdistrict":{"allOf":[{"$ref":"#/components/schemas/AdminIdSection"}],"description":"subdistrict ID in HERE Map Content"},"cmVersion":{"allOf":[{"$ref":"#/components/schemas/CmVersionSection"}],"description":"cmVerison info in HERE Map Content"}}},"RelatedAddress":{"type":"object","required":["relationship","id"],"properties":{"relationship":{"type":"string","enum":["MPA","intersection","nearbyAddress","parentPA"],"description":"\n\nDescription of supported values:\n\n- **RESTRICTED** `MPA`: Micro Point Addresses related to a result items with\n  `resultType` = `houseNumber` and `houseNumberType` = `PA`;\n  for example, buildings, floors (levels) or suites (units)\n  associated to this address. This type of relationship is\n  only returned by the Lookup endpoint and the Geocode endpoint\n  when the `showRelated=MPA` parameter is provided.\n- `intersection`: The Intersections nearest to the address. This type of relationship is\n  only returned by Reverse Geocode, Geocode or Multi-Reverse Geocode\n  endpoints when `showRelated=intersections` parameter is provided.\n- `nearbyAddress`: Nearby address on the same street of main result. This type of\n  relationship is only returned by Reverse Geocode endpoint or\n  Multi-Reverse Geocode endpoint when `showRelated=nearbyAddress`\n  parameter is provided.\n- **RESTRICTED** `parentPA`: The Point Address to which the Micro Point Address\n  belongs; for example the house number to which this\n  suite is associated. This type of relationship is only\n  returned by the Lookup, the Geocode and the (Multi) Reverse Geocode endpoints when\n  the `showRelated=parentPA` parameter is provided."},"title":{"type":"string","description":"The localized display name of this related entity."},"id":{"type":"string","description":"The ID of the related entity."},"resultType":{"type":"string","enum":["addressBlock","administrativeArea","houseNumber","intersection","locality","place","postalCodePoint","street"],"description":"The resultType of the related entity."},"houseNumberType":{"type":"string","enum":["MPA","PA","interpolated"],"description":"The houseNumberType of the related entity.\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."},"address":{"allOf":[{"$ref":"#/components/schemas/RelatedResultAddress"}],"description":"The address of the related entity. The fields are only rendered, if they differ from the main result item."},"position":{"allOf":[{"$ref":"#/components/schemas/DisplayResponseCoordinate"}],"description":"The coordinates (latitude, longitude) of a pin on a map corresponding to the searched place."},"access":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/BasicAccessPoint"}]},"description":"Coordinates of the response item on a HERE map navigable link (for example, for driving or walking)."},"distance":{"type":"integer","format":"int64","description":"The distance \"as the crow flies\" from the search center to this related address' position in meters.\nIt is only returned by Reverse Geocode endpoint or Multi-Reverse Geocode endpoint."},"routeDistance":{"type":"integer","format":"int64","description":"The distance from routing position of the nearby address to the street result, the distance is\ncalculated based on the underlying road geometry. It is only returned by Reverse Geocode endpoint or\nMulti-Reverse Geocode endpoint."},"bearing":{"type":"integer","format":"int32","description":"Bearing (measured clockwise from true north) from the projected coordinate on the street to the\ndisplay position of the related location. True clockwise degree, 0 is north. It is only returned by\nReverse Geocode endpoint or Multi-Reverse Geocode endpoint."},"mapView":{"allOf":[{"$ref":"#/components/schemas/MapView"}],"description":"The bounding box enclosing the geometric shape (area or line) that the related address covers. It is\n only returned by Reverse Geocode endpoint or Multi-Reverse Geocode endpoint."},"mapReferences":{"allOf":[{"$ref":"#/components/schemas/MapReferenceSection"}],"description":"Return the map references of the location objects. It is only returned by Reverse Geocode endpoint\nor Multi-Reverse Geocode endpoint."}}},"NavigationAttributes":{"type":"object","properties":{"speedLimits":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SpeedLimit"}]},"description":"Speed limit for the navigable road following the direction of traffic on the street. If traffic is allowed in both directions\ntwo value sets will be returned. If the request contained a bearing parameter, then the first entry will match the returned\ndirection."},"functionalClass":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/FunctionalClass"}]},"description":"The value represents one of the five levels:"},"access":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Access"}]},"description":"The following boolean values are available for access attributes:"},"physical":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Physical"}]},"description":"The following boolean values are available for physical attributes:"}}},"LinkInfoSection":{"type":"object","required":["cmId","side"],"properties":{"cmId":{"type":"string","description":"link ID in HERE core map"},"side":{"type":"string","description":"The side of the link the attribute is applicable to\n\n- for `resultType=houseNumber` and `resultType=place`: side of the entity to the link\n- for `resultType=street`:\n  - on endpoints *Geocode* and *Lookup*: side of the entity to the link, it is always \"both\"\n  - on endpoints *Reverse Geocode* and *Multi-Reverse Geocode*: relative side from input to the link\n"}}},"PointAddressSection":{"type":"object","required":["hmcId"],"properties":{"hmcId":{"type":"string","description":"The point address ID in HERE Map Content"},"partitionId":{"type":"string","description":"**ALPHA**\n\nUnique identifier that references a specific subset of geo-location related layers\n(e.g., address, location, street, or place) in the HERE Map Content"}}},"MicroPointAddressSection":{"type":"object","required":["hmcId"],"properties":{"hmcId":{"type":"string","description":"The micro point address ID in HERE Map Content"},"partitionId":{"type":"string","description":"**ALPHA**\n\nUnique identifier that references a specific subset of geo-location related layers\n(e.g., address, location, street, or place) in the HERE Map Content"}}},"Segment":{"type":"object","properties":{"ref":{"type":"string","description":"The segment reference follows the format `{segmentId}(#{offset})?`,\nrepresenting its relative position from the result location to a segment."},"side":{"type":"string","description":"The side of the link the attribute is applicable to\n\n- for `resultType=houseNumber` and `resultType=place`: side of the entity to the link\n- for `resultType=street`:\n  - on endpoints *Geocode* and *Lookup*: side of the entity to the link, it is always \"both\"\n  - on endpoints *Reverse Geocode* and *Multi-Reverse Geocode*: relative side from input to the link\n"}}},"AdminIdSection":{"type":"object","required":["hmcId"],"properties":{"hmcId":{"type":"string","description":"Admin ID in HERE Map Content"},"partitionId":{"type":"string","description":"**ALPHA**\n\nUnique identifier that references a specific subset of geo-location related layers\n(e.g., address, location, street, or place) in the HERE Map Content"}}},"CmVersionSection":{"type":"object","required":["region","dvn"],"properties":{"region":{"type":"string","description":"Region ID"},"dvn":{"type":"string","description":"Map version details (DVN) containing the base line for the map schema and an identifier for the weekly or quarterly update.\n\n- Format: YYQ<weekly/quaterly update>\n  - Example: 23150 (map schema: Q1/2023, weekly update 50)\n"}}},"RelatedResultAddress":{"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."},"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":"defining a Micro Point Address. Combines unit name (suite, flat, etc.), level name (floor) and\nbuilding unit name for a Micro Point Address"}}},"SpeedLimit":{"type":"object","required":["maxSpeed","speedUnit"],"properties":{"maxSpeed":{"type":"integer","format":"int32","description":"Used in combination with speed limit unit to indicate allowable speed limit at a location, for unlimited speed, the value is \"999\""},"direction":{"type":"string","enum":["E","N","NE","NW","S","SE","SW","W"],"description":"Rendered in compass value, which is N, S, E, W, NE, SE, NW, SW"},"speedUnit":{"type":"string","enum":["kph","mph"],"description":"Country defined speed unit"},"source":{"type":"string","enum":["derived","posted"],"description":"A generalised identification of the source of `Speed Limit` information.\n\nDescription of supported values:\n\n- `derived`: Based on administrative regulations, for example: highway exit/entry ramps that do not have posted speed limits.\n- `posted`: Based on a posted speed limit sign, speed limit information painted on the road, or data obtained from official sources."}}},"FunctionalClass":{"type":"object","required":["value"],"properties":{"value":{"type":"string","enum":["1","2","3","4","5"],"description":"\n\nDescription of supported values:\n\n- `1`: allowing for high volume, maximum speed traffic movement\n- `2`: allowing for high volume, high speed traffic movement\n- `3`: providing a high volume of traffic movement\n- `4`: providing for a high volume of traffic movement at moderate speeds between neighbourhoods\n- `5`: roads whose volume and traffic movement are below the level of any functional class"}}},"Access":{"type":"object","properties":{"automobiles":{"type":"boolean","description":"Applicable to automobiles.\n\n- `true`: The road allows automobiles.\n- `false`: The road doesn't allow automobiles.\n"},"bicycles":{"type":"boolean","description":"Applicable to bicycles.\n\n- `true`: The road allows bicycles.\n- `false`: The road doesn't allow bicycles.\n"},"buses":{"type":"boolean","description":"Applicable to buses.\n\n- `true`: The road allows buses.\n- `false`: The road doesn't allow buses.\n"},"carpools":{"type":"boolean","description":"Applicable to carpools.\n\n- `true`: The road allows carpooling.\n- `false`: The road doesn't allow carpooling.\n"},"deliveries":{"type":"boolean","description":"Applicable to deliveries.\n\n- `true`: The road allows deliveries.\n- `false`: The road doesn't allow deliveries.\n"},"emergencyVehicles":{"type":"boolean","description":"Applicable to emergency vehicles.\n\n- `true`: The road allows emergency vehicles.\n- `false`: The road doesn't allow emergency vehicles.\n"},"motorcycles":{"type":"boolean","description":"Applicable to motorcycles.\n\n- `true`: The road allows motorcycles.\n- `false`: The road doesn't allow motorcycles.\n"},"pedestrians":{"type":"boolean","description":"Applicable to pedestrians.\n\n- `true`: The road allows pedestrians.\n- `false`: The road doesn't allow pedestrians.\n"},"taxis":{"type":"boolean","description":"Applicable to taxis.\n\n- `true`: The road allows taxis.\n- `false`: The road doesn't allow taxis.\n"},"throughTraffic":{"type":"boolean","description":"Applicable to through traffic.\n\n- `true`: The road allows through traffic.\n- `false`: The road doesn't allow through traffic.\n"},"trucks":{"type":"boolean","description":"Applicable to trucks.\n\n- `true`: The road allows trucks.\n- `false`: The road doesn't allow trucks.\n"}}},"Physical":{"type":"object","properties":{"boatFerry":{"type":"boolean","description":"The segment represents a generalised route of a boat ferry for passengers or vehicles over water,\nincluding routes to pedestrian only islands, tourist areas, commuter ferry routes open to only pedestrians, etc.\n\n- `true`: The road is a boat ferry.\n- `false`: The road isn't a boat ferry."},"bridge":{"type":"boolean","description":"Identifies a structure that allows a road, railway, or walkway to pass over another road,\nrailway, waterway, or valley serving map display and route guidance functionalities.\n\n- `true`: The road is a bridge.\n- `false`: The road isn't a bridge."},"deliveryRoad":{"type":"boolean","description":"Indication of a delivery road.\n\n- `true`: The physical characteristic of the road is that it functions as a delivery road.\n- `false`: The physical characteristic of the road is that it doesn't function as a delivery road."},"movableBridge":{"type":"boolean","description":"Movable Bridge indicates a bridge that moves to allow passage (usually) for boats or barges.\n\n- `true`: The road is a movable bridge.\n- `false`: The road isn't a movable bridge.\n"},"multiplyDigitized":{"type":"boolean","description":"Multiply Digitised identifies separately digitised roads, i.e., roads that are digitised with one line per\ndirection of traffic instead of one line per road.\n\n- `true`: The physical characteristic of the road is that it functions as multiplyDigitized.\n- `false`: The physical characteristic of the road is that it doesn't function as multiplyDigitized."},"paved":{"type":"boolean","description":"Indicates whether the navigable segment is paved.\n\n- `true`: The physical characteristic of the road is paved.\n- `false`: The physical characteristic of the road isn't paved."},"private":{"type":"boolean","description":"Private identifies roads that are not maintained by an organisation responsible for maintenance of\npublic roads.\n\n- `true`: The road is private..\n- `false`: The road isn't private."},"railFerry":{"type":"boolean","description":"The segment represents a generalised route of a ferry for passengers or vehicles via rail.\n\n- `true`: The road is a rail flerry.\n- `false`: The road isn't a rail flerry.\n"},"tunnel":{"type":"boolean","description":"Identifies an enclosed (on all sides) passageway through or under an obstruction.\n\n- `true`: The road is a tunnel.\n- `false`: The road isn't a tunnel.\n"}}}},"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"}}}}