This article is about parsing the output of the API. You may wish to learn how to query into the API first in order to obtain output.
Response format
Our API outputs a JSON
or XML string based on
the "Accept" HTTP request header. A value of text/xml or application/xml
will provide XML output. Any other value, or a missing "Accept" header, will provide JSON output.
JSON
JSON is a newer and simpler alternative to heavyweight (and slow) XML/SOAP configurations. It is natively interpreted by Javascript and is ready to execute, and most other languages and platforms support JSON. We have sample code which shows you how to parse JSON in several languages.
Note: The structure of our JSON response is subject to change. Your code should be able to support any additional or missing fields in JSON responses. See changes and optimizations for more information.
The JSON payload is an array of dynamic "address" objects, as shown below.
Empty response (single address)
This is returned when an input address cannot be validated at all; the request was successful, but there is no data to return because the address is bad.
JSON (Accept: "application/json")
[]
Populated response (single address)
This is returned when an input address is matched to at least one valid address.
JSON (Accept: "application/json")
[
{
"input_index": 0,
"candidate_index": 0,
"delivery_line_1": "1 Infinite Loop",
"last_line": "Cupertino CA 95014-2083",
"delivery_point_barcode": "950142083017",
"components": {
"primary_number": "1",
"street_name": "Infinite",
"street_suffix": "Loop",
"city_name": "Cupertino",
"state_abbreviation": "CA",
"zipcode": "95014",
"plus4_code": "2083",
"delivery_point": "01",
"delivery_point_check_digit": "7"
},
"metadata": {
"record_type": "S",
"county_fips": "06085",
"county_name": "Santa Clara",
"carrier_route": "C067",
"congressional_district": "15",
"rdi": "Commercial",
"latitude": 37.33118,
"longitude": -122.03062,
"precision": "Zip9"
},
"analysis": {
"dpv_match_code": "Y",
"dpv_footnotes": "AABB",
"dpv_cmra": "N",
"dpv_vacant": "N",
"active": "Y"
}
}
]
In the case of multiple matches for a single address, the array in the response will contain more address objects. Each subsequent candidate will have an incremented "candidate_index".
Populated response (multiple addresses)
When you submit multiple addresses in a single request, an input
index is utilized, with the first entry being 0. Each subsequent
entry is incremented by one. When an address within the request
is invalid, there will be no response and the corresponding
input_index entry will be omitted from the result. Thus you can
end up with fewer responses than you started with, though the
input_index will still be accurate. If you submit 6 address
records in a single request and record 4 is invalid, you
will end up with a response like this in the input_index field:
0, 1, 2, 4, 5. See example below:
JSON (Accept: "application/json")
[
{
"input_index": 0,
"candidate_index": 0,
"delivery_line_1": "1 Infinite Loop",
"last_line": "Cupertino CA 95014-2083",
"delivery_point_barcode": "950142083017",
"components": {
"primary_number": "1",
--TRUNCATED FOR BREVITY--
},
{
"input_index": 1,
"candidate_index": 0,
"delivery_line_1": "1600 Amphitheatre Pkwy",
"last_line": "Mountain View CA 94043-1351",
"delivery_point_barcode": "940431351000",
"components": {
"primary_number": "1600",
--TRUNCATED FOR BREVITY--
{
"input_index": 2,
"candidate_index": 0,
"delivery_line_1": "1402 W Center St",
"last_line": "Orem UT 84057-5105",
"delivery_point_barcode": "840575105023",
"components": {
"primary_number": "1402",
--TRUNCATED FOR BREVITY--
},
{
"input_index": 4,
"candidate_index": 0,
"delivery_line_1": "3214 N University Ave # 409",
"last_line": "Provo UT 84604-4405",
"delivery_point_barcode": "846044405140",
"components": {
"primary_number": "3214",
--TRUNCATED FOR BREVITY--
},
{
"input_index": 5,
"candidate_index": 0,
"delivery_line_1": "1 W 100th St",
"last_line": "New York NY 10025-4857",
"delivery_point_barcode": "100254857990",
"components": {
"primary_number": "1",
--TRUNCATED FOR BREVITY--
}
]
Notice "input_index": 3 is missing. That means the 4th address submitted in that batch was
not valid. You will need to track the number of addresses
that you send in each request so that you can accurately
account for them in the output. Failure to do so can lead
to synchronization problems between your input records and
the output data.
XML
The schema for XML request and response payloads is documented in the XSD files provided below:
- Request XSD file
- Response XSD file — Note: The structure of our XML response may change as we roll out improvements to the API. Your code should be able to support any additional or missing fields in the XML. We'll update the response XSD file should this happen.
These files can be used in conjunction with various 3rd-party tools/libraries to generate code that corresponds to the XML schema contained in the XSD files that will allow easier mapping between XML and code. Below is a listing of commonly used tools in various programming languages as well as where to go to find more information:
Java
.Net
- Xsd2Code - NOTE: When using this tool to generate classes from our XSD files you must set the GenerateXMLAttributes option to True (see the answer to this question)
- Related discussion
PHP
Python
Ruby
Empty response
This is returned when an input address cannot be validated at all; the request was successful, but there is no data to return because the address is bad.
XML (Accept: "text/xml")
<?xml version="1.0" encoding="utf-8"?>
<candidates />
Populated response
This is returned when an input address is matched to at least one valid address.
XML (Accept: "text/xml")
<?xml version="1.0" encoding="utf-8"?>
<candidates>
<candidate>
<input_index>0</input_index>
<candidate_index>0</candidate_index>
<delivery_line_1>1 Infinite Loop</delivery_line_1>
<last_line>Cupertino CA 95014-2083</last_line>
<delivery_point_barcode>950142083017</delivery_point_barcode>
<components>
<primary_number>1</primary_number>
<street_name>Infinite</street_name>
<street_suffix>Loop</street_suffix>
<city_name>Cupertino</city_name>
<state_abbreviation>CA</state_abbreviation>
<zipcode>95014</zipcode>
<plus4_code>2083</plus4_code>
<delivery_point>01</delivery_point>
<delivery_point_check_digit>7</delivery_point_check_digit>
</components>
<metadata>
<record_type>S</record_type>
<county_fips>06085</county_fips>
<county_name>Santa Clara</county_name>
<carrier_route>C067</carrier_route>
<congressional_district>15</congressional_district>
<rdi>Commercial</rdi>
<latitude>37.33118</latitude>
<longitude>-122.03062</longitude>
<precision>Zip9</precision>
</metadata>
<analysis>
<dpv_match_code>Y</dpv_match_code>
<dpv_footnotes>AABB</dpv_footnotes>
<dpv_cmra>N</dpv_cmra>
<dpv_vacant>N</dpv_vacant>
<active>Y</active>
<ews_match>false</ews_match>
</analysis>
</candidate>
</candidates>
In the event that more candidates (or matches) are returned for an ambiguous address, expect to see more nodes in the response. Each subsequent candidate will have an incremented "candidate_index".
Field definitions
See the field definitions guide for information about data types and lengths, and descriptions of each field returned by the API.
Changes and optimizations
From time to time, we will introduce new fields into the schema.
Never expect certain fields to be present in the output of any API.
The ordering and number of fields in the response may change.
Fields will not be removed from the response schema once introduced
into production. However, fields which contain null, empty, or default values
(such as false, 0, or "")
may not be serialized into the actual response, depending on the serializer
and whether the output is JSON or XML. To preserve bandwidth and increase
performance, extra whitespace will be removed from the response text.