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 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
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
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
In a CSV response this value will be stated in the header section. If it is zero the ResponseFaultList will not be present.
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.
The GeocodeResponseList is a list of geocoded addresses. The number of elements on the list is given by the numberOfGeocodedAddresses field.
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
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
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
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.
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.
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.
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
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.
Unit
This is generally an internal building subdivider
Building
This is a separate building identifier where a single CompleteAddressNumber identifies more than one building
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
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.
This is the identifier for a SiteAddress.
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.
This is the post office name for this address. This may occur in a SiteAddress or IntersectionAddress.
This is the state in which the address is located. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.
This is the 5 digit USPS postal code for the address. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.
This is the 4 digit extension to the USPS postal code. This may occur in a SiteAddress, IntersectionAddress or the RequestedAddress.