Batch Geocoder API Developer's Guide

Reading batch request output

The output data produced as a result of a successful batch geocoding or reverse batch geocoding request includes the data items specified in the original job request. The layout of the output is the same irrespective of whether the request is for geocoding or reverse geocoding. The first three columns are fixed and are always:

recId
seqNumber
seqLength

recId is the same ID you provided in the input. seqNumber and seqLength are used to number ambiguous results for an input address. For example, the input "425 Randolph St" produces two results: E and W Randolph St. The seqLength is the number of records returned, which is 2 in this case, and both results are sorted by seqNumber. There is no guarantee that the result is sorted by recId and seqNumber.

In the example below the complete output for the example input data in Input data can be found:

recId|seqNumber|seqLength|displayLatitude|displayLongitude |houseNumber|street|city|postalCode|country|
1|1|2|41.8838692|-87.6389008|425|W Randolph St|Chicago|60606|USA
1|2|2|41.8842278|-87.6169052|425|E Randolph St|Chicago|60601|USA
2|1|1|42.3508682|-71.0714874|31|Saint James Ave|Boston|02116|USA
3|1|1|52.5304108|13.3852701|117|Invalidenstraße|Berlin|10115|DEU

Basic output fields

Table 1. General
`recId`	Identifies your input address in the response
`seqNumber`	Consecutively numbers the different results for the corresponding input record starting with 1
`seqLength`	Number of results for the corresponding input record

Table 2. Geographical Location
`displayLatitude`	Latitude of display position
`displayLongitude`	Longitude of display position
`navigationLatitude` (same as `latitude`)	Latitude of navigation position
`navigationLongitude` (same as `longitude`)	Longitude of navigation position
`mapViewBottomRightLatitude`	Latitude of mapview's bottom right corner
`mapViewBottomRightLongitude`	Longitude of mapview's bottom right corner
`mapViewTopLeftLatitude` (same as `latitude`)	Latitude of mapview's top left corner
`mapViewTopLeftLongitude` (same as `longitude`)	Longitude of mapview's top left corner

Table 3. Address
`street`	Refers to the street name.
`houseNumber`	House number. Depending on regional characteristics, can also be house name. For API implementations which do not support separate street and house number fields, this field can be omitted.
`building`	Building name
`subdistrict`	Includes the subdivision level below the district. This field is currently only used for India results. In India, it is typical to use the names of areas below district level in addressing.
`district`	Includes the subdivision level below the city. Use of this field is optional if a second subdivision level is not available.
`city`	Refers to the locality of the address.
`postalCode`	Postal code
`county`	Includes the second subdivision level(s) below the country. Use of this field is optional if a second subdivision level is not available.
`state`	Includes the first subdivision level(s) below the country. Where commonly used, this is a state code (for instance, CA for California).
`country`	ISO 3166-alpha-3 country code
`addressLines`	Formatted address lines built out of the parsed address components. The first line consists of street name, including prefix, directional and street type, and house number. The second line consists of the city name and postal code, plus in some countries the state name or abbreviation. These elements are only populated if the `MatchLevel` is street or better. A city match does not contain address lines.
`addressAdditionalData`	Secondary address units as defined by the US Postal Service can be recognized and returned if the PreserveUnitDesignators switch was set to true in the SearchRequest additionalData field. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry. Examples of such keys include the following values: `APT` recognized value of unit type Apartment `BLDG` recognized value of unit type Building `FL` recognized value of unit type Floor `STE` recognized value of unit type Suite `UNIT` recognized value of unit type Unit `UNIT`x recognized value of unit type Department `UnknownUnit` unrecognized address unit value, which is usually printed with a pound (#) sign Example:`CountryName=Vereinigte Staaten; StateName=Illinois`

Table 4. Formatted Localized Address
`locationLabel`	Assembled address value for displaying purposes.

Table 5. Address Match Information
`relevance`	Indicates the relevance of the results found; the higher the score the more relevant the alternative. The score is a normalized value between 0 and 1.
`matchType`	Quality of the location match. `pointAddress:` Location matches exactly as point address. `interpolated:` Location was interpolated.
`matchCode`	Code indicating how well the result matches the request. Enumeration [`exact`, `ambiguous`, `upHierarchy`, `ambiguousUpHierarchy`].
`matchLevel`	The most detailed address field that matched the input record
`matchQualityStreet`	MatchQuality provides detailed information about the match quality of a result at attribute level. Match quality is a value between 0.0 and 1.0. 1.0 represents a 100% match. (For example, `matchQualityCity` is the quality of the result with respect to the city information.)
`matchQualityHouseNumber`
`matchQualityBuilding`
`matchQualityDistrict`
`matchQualityCity`
`matchQualityPostalCode`
`matchQualityCounty`
`matchQualityState`
`matchQualityCountry`

The attributes below refer to different aspects of the Map Object used in the response.

Note: Requires the addition of locationattributes= (one of mr, mapReference, all) to the request or to add the locationattributes column with value mr, mapReference, or all to the input.

Table 6. Map Reference
`mapReferenceId`	PVID of the link (for address level results).
`mapReferenceMapId`	Map version details containing the base line for the map schema and an identifier for the weekly update. Format: <4-letter region>`YYQ`<weekly update> Example: NAAM15135 (region: North America (NAAM), map schema: Q1/2015 (151), weekly update 35)
`mapReferenceMapVersion`	Version of the map schema. Format: QQ/YYYY, (for example, Q3/2016)
`mapReferenceMapReleaseDate`	Release date of the map data. Format: YYYY-MM-DD
`mapReferenceSideOfStreet`	Indicates whether the referenced location is on the left or right side of the link (if heading from the reference node to the non-reference node). Enumeration [`left`, `right`, `neither`]
`mapReferenceSpot`	Relative position of the location along the link. Spot is defined as the fractional distance from the link's reference-node to the non-reference node: the value range is between 0 and 1. This attribute is only relevant if a link is referenced.
`mapReferenceCountryId`	PVID of the country admin area.
`mapReferenceStateId`	PVID of the state admin area.
`mapReferenceCountyId`	PVID of the county admin area.
`mapReferenceCityId`	PVID of the city admin area.
`mapReferenceDistrictId`	PVID of the district admin area.
`mapReferenceAddressId`	PVID of the Point Address. Only available for results with `matchLevel` `houseNumber` and `matchType` `pointAddress`. Not available for `interpolated` results.

The address details type provides additional information about the address. The names for address elements are listed together with the language information for this name.

Note: Requires the addition of locationattributes= (one of dt, addressDetails, all) to the request or to add locationattributes column with value dt, addressDetails, or all to the input.

Table 7. Address Details
`addressDetailsCountryCode`	ISO 3166-alpha-3 country code.
`addressDetailsCountry`	Country name.
`addressDetailsCountryLanguage`	Country language information.
`addressDetailsState`	State name.
`addressDetailsStateLanguage`	State language information.
`addressDetailsCounty`	County name.
`addressDetailsCountyLanguage`	County language information.
`addressDetailsCity`	City name.
`addressDetailsCityLanguage`	City language information.
`addressDetailsDistrict`	District name.
`addressDetailsDistrictLanguage`	District language information.
`addressDetailsStreet`	Street name.
`addressDetailsStreetLanguage`	Street language information.
`addressDetailsHouseNumber`	House number.
`addressDetailsHouseNumberLanguage`	House number language information.
`addressDetailsPostalCode`	Postal code.
`addressDetailsBuilding`	Building name.
`addressDetailsBuildingLanguage`	Building language information.

The street details type provides additional information about the street. The Street Details type decomposes the street name into its name parts like the base name, the street type, and other information.

Note: Requires the addition of locationattributes= (one of sd, streetDetails, all) to the request or to add locationattributes column with value sd, streetDetails, or all to the input.

Table 8. Street Details
`addressDetailsStreetDetailsBaseName`	Base name part of the street name. The base name is a numbered route, local name, or commonly accepted name for a street.
`addressDetailsStreetDetailsPrefix`	A prefix is a directional identifier that precedes, but is not included in, the base name of a road.
`addressDetailsStreetDetailsSuffix`	A suffix is a directional identifier that follows, but is not included in, the base name of a road.
`addressDetailsStreetDetailsDirection`	Indicates the official directional identifiers assigned to highways, typically either "North/South" or "East/West".
`addressDetailsStreetDetailsStreetType`	Street type part of the street name. Street type is the local municipality designator of each road, such as "street", "road", "strasse", "straat", "via", or "rue de la". Street types are defined as either "preceding" or "following" the base name and "attached" or "unattached" to the base name.
`addressDetailsStreetDetailsStreetTypeBefore`	Defines if the street type is before or after the base name.
`addressDetailsStreetDetailsStreetTypeAttached`	Defines if the street type is attached or unattached to the base name.

Table 9. Miscellaneous
`locationType`	Indicates whether the location is an [area, point, line].
`locationId`	A key uniquely identifying a physical location.
`responseAdditionalData`	Additional information about the result, such as house number fallbacks: `houseNumberFallbackDifference=1; houseNumberFallback=true`

Table 10. Parsed Request Information
`parsedRequestName`	Input token(s) the parser has categorized as the name of a landmark.
`parsedRequestLabel`	Assembled address value built out of the parsed address components.
`parsedRequestCountry`	Input token(s) the parser has categorized as the country part of an address.
`parsedRequestState`	Input token(s) the parser has categorized as the state part of an address.
`parsedRequestStreet`	Input token(s) the parser has categorized as the street part of an address (including intersections which are defined by two streets).
`parsedRequestCounty`	Input token(s) the parser has categorized as the county part of an address.
`parsedRequestCity`	Input token(s) the parser has categorized as the city part of an address.
`parsedRequestDistrict`	Input token(s) the parser has categorized as the district part of an address.
`parsedRequestSubDistrict`	Input token(s) the parser has categorized as the subdistrict part of an address.
`parsedRequestHouseNumber`	Input token(s) the parser has categorized as the house number part of an address.
`parsedRequestPostalCode`	Input token(s) the parser has categorized as the postal code part of an address.
`parsedRequestBuilding`	Input token(s) the parser has categorized as the building part of an address.
`parsedRequestAddressLines`	Formatted address lines built out of the parsed address components. The first line consists of a street name, including prefix, directional and street type, and house number. The second line consists of the city name and postal code, plus in some countries the state name or abbreviation. These elements are only populated if the `MatchLevel` is street or better. A city match does not contain address lines.
`parsedRequestAdditionalData`	Secondary address units as defined by the US Postal Service built out of the parsed address components. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry. Examples of such keys include the following values: `APT` recognized value of unit type Apartment `BLDG` recognized value of unit type Building `FL` recognized value of unit type Floor `STE` recognized value of unit type Suite `UNIT` recognized value of unit type Unit `UNIT`x recognized value of unit type Department `UnknownUnit` unrecognized address unit value, which is usually printed with a pound (#) sign Example:`CountryName=Vereinigte Staaten; StateName=Illinois`
`parsedRequestPosition`	Input token(s) the parser has categorized as the position of the request.