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
  • UNITx 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
  • UNITx 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.