API Reference

The request and response format for the /validate-address endpoint, and every input and output field.

Endpoint

The server's API endpoint can be queried using curl, for example:

POST /validate-address
curl --request POST \
  --url http://localhost:8080/validate-address \
  --header 'Content-Type: application/json' \
  --data '{
    "Name_Firm": "",
    "Primary_Address": "101 State St nw",
    "Secondary_Address": "",
    "Locality": "La Crosse",
    "Region": "wi",
    "Postcode": ""
}'

A successful response to a /validate-address call will look like this:

Response
{
  "carrier_route_sort_zone": "D",
  "cart": "C019",
  "check_digit": "5",
  "city": "La Crosse",
  "cmra_flag": "N",
  "congress_district": "3",
  "county_name": "La Crosse",
  "delivery_type": "P",
  "dpbc": "01",
  "dpv_footnotes": "AABB",
  "dpv_no_stat_flag": "N",
  "dpv_status": "Y",
  "dpv_vacant_flag": "N",
  "fault_code": "",
  "fips_code": "55063",
  "full_address": "101 State St",
  "lastline": "La Crosse WI 54601-3221",
  "post_directional": "",
  "pre_directional": "",
  "primary_address": "101 State St",
  "primary_name": "State",
  "primary_number": "101",
  "primary_secondary_address": "101 State St",
  "rdi_indicator": "N",
  "record_type": "S",
  "secondary_address": "",
  "secondary_description": "",
  "secondary_number": "",
  "state": "WI",
  "status_code": "S94000",
  "suffix": "St",
  "undeliverable": "F",
  "urbanization_name": "",
  "zip4": "3221",
  "zip5": "54601"
}

Input Fields

Note: These input fields are what the AIQ Realtime Services endpoint accepts by default. Custom configurations provided to the service may change this interface.
Field nameDescriptionExample
Name_FirmThe company name. Optional.Charmant Hotel
Primary_AddressThe delivery address line that includes information like the house number, street name, and unit information.101 State St
Secondary_AddressDelivery address line that can include various types of address information. Optional.
LocalityThe city, town, or suburb.La Crosse
RegionThe name of the state or province for this address.WI
PostcodeThe five-digit primary ZIP Code. This field does not include the 4-digit ZIP4 Code. Optional.

Output Fields

Note: These output fields are what the AIQ Realtime Services endpoint returns by default. Custom configurations provided to the service may change this interface.
Field nameDescription
carrier_route_sort_zoneCarrier-route sort zone; indicates eligibility for Standard Mail Automation Enhanced Carrier Route.
  • A Carrier route rates are available and merging is allowed.
  • B Carrier route rates are available and merging is not allowed.
  • C Carrier route rates are not available and merging is allowed.
  • D Carrier route rates are not available and merging is not allowed.
congress_districtThree-digit district number for the U.S. House of Representatives.
dpbcContains the two-digit Delivery Point Bar Code (DPBC).
fips_codeContains the Federal Information Processing Standards (FIPS) code for state and county. Combines the 2-digit state code with the 3-digit county code. Note: U.S. territories, possessions, or protectorates such as Puerto Rico, the U.S. Virgin Islands, or the Pacific Islands don't have FIPS state digits.
cartThe Carrier Route.
full_addressThe address line of the address.
lastlineThe last City, State, and ZIP code information of the address.
undeliverableDeliverability indicator.
  • T: True; undeliverable.
  • F: False; deliverable.
urbanization_nameContains the full urbanization name. Applicable to Puerto Rico territory.
county_nameContains the full county name.
delivery_typeContains the type of postal facility:
  • A: Airport Mail Facility (AMF)
  • B: Branch Office
  • C: Community Post Office (CPO)
  • D: Area Distribution Center (ADC)
  • E: Sectional Center Facility (SCF)
  • F: Delivery Distribution
  • G: General Mail Facility (GMF)
  • K: Network Distribution Centers (NDC)
  • M: Money Order Unit
  • N: City/place name
  • P: Post Office (main)
  • S: Station
  • U: Urbanization (Puerto Rico only)
cmra_flagContains the DPV Commercial Mail Receiving Agency (CMRA) component that the transform generated for this record.
  • L: Address triggered DPV locking.
  • N: Address isn't a CMRA.
  • Y: Address is a valid CMRA.
  • blank: Blank output value indicates that the ENABLE_DPV_VALIDATION option was set to NO, the software locked DPV processing, or the transform couldn't assign the input address.
dpv_footnotesUp to 12 characters. DPV footnotes are required for end-user CASS certification. The footnotes contain the following information:
  • AA: Input address matches to the ZIP+4 file (records NOT assigned an error code except E600).
  • A1: Input address does not match to the ZIP+4 file (all records assigned an error code except E600).
  • BB: All input address components match to DPV (DPV_Status = Y).
  • CC: Input address primary number matches to DPV but the secondary number does not match (DPV_Status = S: the secondary is present but invalid).
  • F1: Input address matches a military address.
  • G1: Input address matches a general delivery address.
  • IA: Informed address identified.
  • M1: Input address primary number is missing (error codes E420 or E302).
  • M3: Input address primary number is invalid (DPV_Status = N and error code is NOT E600, or if just the DPV_Status = L).
  • N1: Input address primary number matches DPV, but the address is missing the secondary number (DPV_Status = D).
  • PB: Identified PO Box Street Address.
  • P1: Input address RR or HC box number missing.
  • P3: Input address PO, RR, or HC number invalid.
  • RR: Input address matches to CMRA (DPV_CMRA = Y).
  • R1: Input address matches to CMRA but the secondary number is not present.
  • R7: Addresses that are assigned to a phantom route of R777 or R779.
  • TA: Input address primary number matched by dropping trailing alpha.
  • U1: Input address matches a unique address.
Note: DPV footnotes always post in the same order, and this field will not always be 12 characters in length.
dpv_no_stat_flagContains a value that indicates whether the address is a vacant property, receives mail as part of a drop, or doesn't have an established delivery yet. Output values include:
  • Y: Input address was flagged as No Stat in DPV data. The value in the DPV_NOSTATS_REASON_CODE output field provides the reason for the No Stat status.
  • N: Input address wasn't flagged as No Stat in DPV data.
  • blank: The transform didn't look up the input address.
dpv_statusContains a DPV status component that the transform generated for this record.
  • Y: Both the primary and secondary (if present) input addresses DPV confirmed.
  • S: Input address was DPV confirmed for the primary number only. The secondary number was present but invalid, or a single trailing alpha on a primary number was dropped to make a DPV match.
  • D: Input address was DPV confirmed for the primary number only. The secondary number was missing.
  • N: Input address failed to DPV confirm because the primary number was either missing or invalid.
  • L: Input address triggered DPV locking.
  • blank: Either DPV was disabled, the transform couldn't assign the input address, or DPV processing was disabled by the software because the input address was a false positive.
dpv_vacant_flagContains a vacant address indicator.
  • Y: Input address was vacant.
  • N: Input address wasn't vacant.
  • blank: Input address wasn't looked up.
fault_codeContains a code that indicates why the transform couldn't assign the address. Field is blank when the transform assigned the address.
cityContains the locality.
  • Canada and USA: contains the locality preferred by the postal authority.
  • Other countries: contains the city, town, locality, or suburb.
zip5Contains the 5-digit ZIP Code. Doesn't include the 4-digit ZIP+4.
zip4Contains the four-digit ZIP+4 Code. Located after the primary postal code on a mail piece, either preceded with a hyphen or not. For example, for the full ZIP Code 54601-1234, the value is "1234".
primary_addressContains the primary address line, such as the street address or post office box. Doesn't include secondary address information such as apartment. If you enable the USE_USPS_PRIMARY_NAME_ABBREVIATION option, the transform uses the USPS Primary Name abbreviation first.
primary_nameContains the primary street name description. Note: If output doesn't fit within the length of the output field, the transform truncates the data using intelligent truncation.
primary_numberContains the house or building number.
post_directionalContains the abbreviated directional that follows the street name. For example, N, S, NW, or SE.
pre_directionalContains the abbreviated directional that precedes a street name. For example, N, S, NW, or SE.
primary_secondary_addressContains the primary address and secondary address on one line. Doesn't include remainder data. The software outputs this line as if the INCLUDE_UNUSED_ADDRESS_LINE_DATA option is set to NO. When set to NO, the output doesn't include invalid secondary address line information.
suffixContains the abbreviated street type, such as St, Ave, or Pl.
rdi_indicatorIndicates whether the address is residential.
  • Y: Residential address.
  • N: Nonresidential address.
stateContains the state, province, territory, or region.
secondary_addressContains the building name, floor, and room number in one field.
status_codeContains a code that indicates how the input address differs from the assigned address. Blank when the address is unassigned.
secondary_descriptionContains the unit description, such as #, Apartment, or Flat.
secondary_numberContains the unit number, such as 100 in the unit APT 100.

Geocode Output Fields

Geocoding data appended to each response

When geocoding is enabled, the following fields are available in the response. They can be exposed and customized through the Geocoding_Options section of aiq_config.yml.

Field nameDescription
address_latitudeContains the latitude at the best assigned level, which is 0-90 degrees north or south of the equator. The transform standardizes the latitude to six decimals in the format 45.801357.
address_longitudeContains the longitude at the best assigned level, which is 0-180 degrees east or west of the Greenwich meridian. The transform standardizes the longitude to six decimals in the format 123.458331.
address_match_levelContains the level to which the transform matches the address to the data in the reference files (directories).
  • PRE: Primary Range Exact. Assigns to the exact location of the address (for example, 123 Main St). PRE is the most precise level of assignment. To obtain PRE, map either the POI_TYPE input field or the PRIMARY_NAME and PRIMARY_NUMBER input fields.
  • PRI: Primary Range Interpolated. Assigns to the level of the address range (for example, 100-500 Main St).
  • L1-4: Assigns to the level of city, town, or suburb.
  • P1: Postcode1. Assigns to the level of Postcode1.
  • P2P: Postcode2 Partial. Assigns the full Postcode1 and the first few characters of Postcode2.
  • PF: Postcode Full. Assigns to the level of Postcode1 and Postcode2, when available.
census_tract_blockContains the census tract code as defined by the government for reporting census information. Census tracts are small, relatively permanent statistical subdivisions of a county.
centroid_latitudeContains the latitude at the postcode-level centroid of the postcode. The transform standardizes the latitude to six decimals in the format 45.801357.
centroid_longitudeContains the longitude at the postcode-level centroid of the postcode. The transform standardizes the longitude to six decimals in the format 123.45833.
centroid_match_levelMatch code indicating the precision of the centroid latitude and longitude assignment. The lower the number, the more precise the assignment.
  • 1: 9-digit match in Centroid.
  • 4: 7-digit match in Centroid.
  • 5: 5-digit match in Centroid.
  • 7: No match in Centroid.
  • blank: Not tried.
gov_county_codeContains a unique county code as defined by the government for reporting census information.
gov_locality1_codeContains a unique code for an incorporated municipality such as a city, town, or locality, as defined by the government for reporting census information.
gov_region1_codeContains a unique region code as defined by the government for reporting census information. For example, in the USA, the code is a Federal Information Processing Standard (FIPS) two-digit state code.
info_codeContains a three-character code that provides information about the geocoding results:
  • The third character indicates the status for address and point-of-interest geocoding assignment.
  • The second and third characters indicate the status for reverse geocoding assignment.
  • If assigned to the best level, the INFO_CODE field is blank.
  • The first character is reserved for future use.
stat_area_codeContains a core-based statistical area code where an area has a high degree of social and economic integration within the core that the area surrounds. The government defines the area for reporting census information.
metro_stat_area_codeContains the metropolitan statistical area. A metropolitan statistical area has a large population with a high degree of social and economic integration with the core of the area. The government defines the area for reporting census information.
minor_div_codeContains the minor civil division, or census county division code when the minor civil division is not available. The minor civil division designates the primary government and/or administrative divisions of a county, such as a civil township or precinct.
PreviousConfiguration