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 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.
The content-type of the JSON response is
application/json. The Response is a JSON object.
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.
This is the interface version of the response. It should match the Version of the submitted request. The minimum value is 1.1.
This returns verbatim the RequestID submitted by the sender. It will be blank if no RequestID was submitted.
The value of the GeocodeResponse field is a GeocodeResponse object
The GeocodeResponse object has three elements: The GeocodeResponseList, The ResponseFaultList, and the Requested Address.
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
The ResponseFaultList is a list of error reports and is present only if an error occurs. See the ResponseFaultList object
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.
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.
The faultcode is one of either "Client" or "Server".
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.
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.
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”.
See the Address object
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".
See the GeocodeMatchCode object
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.
See the SiteAddress object
See the IntersectionAddress object
The GeocodeMatchCode field has as its value an object with an accuracy element and a matchType element.
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.
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.
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.
The dataSource field will indicate the file name or other identifier of the dataset from which the address data is taken.
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.
This will be a sequence of precisely two normalized CompleteStreetNames
This is an address identified by a numeric or quasi-numeric identifier and a streetname. The CompleteAddressNumber and CompleteStreetName fields will always be present.
See CompleteStreetName. This will be a normalized, parsed object in a SiteAddress response
See CompleteOccupancyIdentifier. This will be a normalized, parsed object in a SiteAddress response
This is generally an internal building subdivider
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
A pre-positioned qualifier to the street name, such as
Old Highway 99
A directional indicator that precedes the Street name, such as
West 107th Street
This is a street type that precedes the StreetName. For example,
Highway 17, or
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.
The street type that follows the Street Name. For example,
A directional indicator that follows the street name, such as
17th Avenue Northwest
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.