GeocodeService API: The Response


Format of the Response

The format of the Response is governed by the value of the ResponseFormat variable in the client-submitted request. There are, therefore, three possible formats: XML (default), JSON and CSV.

XML

XML is the default format for the response. The content-type of the xml Response is text/xml. An xml schema, GeocodeResponse.xsd, specifies the form.

JSON

The content-type of the JSON response is application/json. The Response is a JSON object.

CSV

The content-type of the CSV Response is text. It will consist of newline-terminated lines of comma-delimited values. For each section that appears in the response the first line will give the element names and will be followed by one or more lines giving the corresponding values.


The Response

The Response is the response received from the GeocodeService. The XML Response structure will have two attributes, the RequestID, the Version, and an element, the GeocodeResponse. The JSON object will have three fields, the RequestID, the Version, and the GeocodeResponse. The The first line of the response is the header field list. The CSV header will have have the four field names "Version", "RequestID", "numberOfGeocodedAddresses", and "numberOfFaults". The values given for the numberOfGeocodedAddresses and numberOfFaults determines the structure of the rest of the response. If the numberOfGeocodedAddresses is non-zero there will be a list of geocoded addresses. If the numberOfFaults is non-zero there will be a list of error reports. If both are non-zero the list of geocoded addresses will precede the list of errors. For each list there will exist, in addition to the values for each item on the list, a header line giving the fieldnames. The final structure is the requested address, which will again consist of a headerline of field names followed by a single line consisting of the corresponding values.

Version

This is the interface version of the response. It should match the Version of the submitted request. The minimum value is 1.1.

RequestID

This returns verbatim the RequestID submitted by the sender. It will be blank if no RequestID was submitted.

GeocodeResponse

The value of the GeocodeResponse field is a GeocodeResponse object


GeocodeResponse

The GeocodeResponse object has three elements: The GeocodeResponseList, The ResponseFaultList, and the Requested Address.

GeocodeResponseList

This contains the list of geocoded match candidates. The GeocodeResponseList is empty if no addresses are returned and absent if an error occurs before it is generated. See the GeocodeResponseList object

ResponseFaultList

The ResponseFaultList is a list of error reports and is present only if an error occurs. See the ResponseFaultList object

RequestedAddress

The RequestedAddress is absent only if an error occurs before it is retrieved. See the RequestedAddress object


ResponseFaultList

The ResponseFaultList object is a sequence of one or more Faults. The number of items on the list will be given by the numberOfFaults.

In an XML response the ResponseFaultList is an element of the GeocodeResponse object. It will contain a sequence of Faults. The numberOfFaults is an attribute of the ResponseFaultList.

In a JSON response the ResponseFaults field will belong to the Response object and will possess the ResponseFaultList field and the numberOfFaults field.

The CSV response will contain a separate header-initiated section. It will contain a header following by a list, one line each of the corresponding reports. The header will read : "faultcode", "faultstring", "detail". There will be one comma-delimited value for each of these fields and thus three values per line.

Fault

If the ResponseFaultList is present in the response, then there will be one or more Faults. See the Fault object. In JSON this will be an array of faults. In XML it will be a sequence of fault objects

numberOfFaults

In a CSV response this value will be stated in the header section. If it is zero the ResponseFaultList will not be present.


Fault

Each fault object will contain three fields: a faultcode, faultstring and a detail field.

faultcode

The faultcode is one of either "Client" or "Server".

faultstring

The faultstring for "Client" is "Bad client content" and for "Server", "Server process error". It should be noted that the expression of these two fault types is not, as it would seem, an assignation of blame.

detail

The detail field will give a brief diagnostic of the fault that may assist either the client or server in correcting the problem encountered. This diagnostic may be an error message generated by the responder or by a software library linked to the responder.


GeocodeResponseList

The GeocodeResponseList is a list of geocoded addresses. The number of elements on the list is given by the numberOfGeocodedAddresses field.

numberOfGeocodedAddresses

This is the number of GeocodedAddresses that appear on the list. This is an integer value that can range from 0 to the maximum (30). In XML this is an attribute.

GeocodedAddress

See the GeocodedAddress object


GeocodedAddress

A GeocodedAddress consists of four parts.

In a JSON response the GeocodedAddress field has as its value an object consisting of the address object, a Point field which has as its value an object with the fields Latitude and Longitude, and a GeocodeMatchCode field. In a CSV response the Address values will be followed by the latitude, longitude, accuracy , matchType, note, dataSource and addressIdentifier fields, all on a single line. The CSV field names will thus be the Address field names followed by "Latitude", "Longitude", "accuracy" , "matchType" , “dataSource” and “addressIdentifier”.

Address

See the Address object

gml:Point

This is the latitude and longitude of the position. In JSON and CSV Address objects the latitude and longitude are represented in separate fields. In XML the field is named "gml:Point".

GeocodeMatchCode

See the GeocodeMatchCode object

source

See the source object


Address

The Address element will contain either a SiteAddress or an IntersectionAddress. The Address is the normalized address of the candidate. It will be articulated in a fashion consistent with the Street Address Data Standard. It will be either a SiteAddress or IntersectionAddress, depending on the nature of the request.

SiteAddress

See the SiteAddress object

IntersectionAddress

See the IntersectionAddress object


GeocodeMatchCode

The GeocodeMatchCode field has as its value an object with an accuracy element and a matchType element.

accuracy

The accuracy field will be a decimal value not less than 0.00 and not more than 1.00 and will indicate the degree of correspondence between the requested address and the normalized reference address.

matchType

The matchType field will contain one of the values "Precise" or "Interpolated", indicating whether the position was determined by matching a record that specified that position or whether the position was determined by matching with an arc record and calculating the ratio of its address number with the range between the starting address number and its position and the ending address number and its position.

note

The note field will contain the value “P” if the returned address disagrees in parity with other addresses in its address range. This is used for “Interpolated” addresses and will be empty if the address is not interpolated or if the parity does not disagree.


source

The source field has as its value an object with a dataSource element and an AddressIdentifier element.

dataSource

The dataSource field will indicate the file name or other identifier of the dataset from which the address data is taken.

addressIdentifier

The addressIdentifier field will indicate the identifier for the specific record from which the address data is taken. This element may be empty for Intersection responses.


IntersectionAddress

An Intersection Address expresses the intersection of two thoroughfares.

Note: Only one set of PlaceStateZip elements are given, despite the fact that there could be more than one at intersections that fall upon a civic or postal boundary.

CompleteStreetName

This will be a sequence of precisely two normalized CompleteStreetNames

PlaceName

See PlaceName.

StateName

See StateName.

ZipCode

See ZipCode.

ZipPlus4

See ZipPlus4.


SiteAddress

This is an address identified by a numeric or quasi-numeric identifier and a streetname. The CompleteAddressNumber and CompleteStreetName fields will always be present.

CompleteAddressNumber

See CompleteAddressNumber

CompleteStreetName

See CompleteStreetName. This will be a normalized, parsed object in a SiteAddress response

CompleteOccupancyIdentifier

See CompleteOccupancyIdentifier. This will be a normalized, parsed object in a SiteAddress response

PlaceName

See PlaceName.

PlaceName_USPS

See PlaceName_USPS.

StateName

See StateName.

ZipCode

See ZipCode.

ZipPlus4

See ZipPlus4.


CompleteOccupancyIdentifier

Unit

This is generally an internal building subdivider

Building

This is a separate building identifier where a single CompleteAddressNumber identifies more than one building


CompleteStreetName

The CompleteStreetName, in the RequestedAddress object, represents the unnormalized, unparsed street name as sent by the client. In the response, the name is normalized and parsed into the below fields. In the normalized CompleteStreetName any one of the fields may be present, but the StreetName is always present

PreModifier

A pre-positioned qualifier to the street name, such as Old in Old Highway 99

PreDirectional

A directional indicator that precedes the Street name, such as West in West 107th Street

PreType

This is a street type that precedes the StreetName. For example, Highway in Highway 17, or Rue in Rue Morgue.

StreetName

This field is always present. It is the base name for the street. This will be the official (unstandardized) name of the Street, as represented in the record.

PostType

The street type that follows the Street Name. For example, Street in Main Street

PostDirectional

A directional indicator that follows the street name, such as Northwest in 17th Avenue Northwest

PostModifier

A post-positioned qualifier to the street name


RequestedAddress

This returns the unnormalized address submitted by the client. The fields stated correspond to those included in the request and will differ, depending on the nature of the Request. There will be, for example, a CompleteStreetName and CompleteStreetName2 field if it is an intersection request.


Other Address Attributes

CompleteAddressNumber

This is the identifier for a SiteAddress.

PlaceName

This is the city, town or municipal name of the area in which the address is located. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.

PlaceName_USPS

This is the post office name for this address. This may occur in a SiteAddress or IntersectionAddress.

StateName

This is the state in which the address is located. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.

ZipCode

This is the 5 digit USPS postal code for the address. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.

ZipPlus4

This is the 4 digit extension to the USPS postal code. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.