AIUS – GetAddressInsight

URL Endpoints

JSON:
- https://trial.serviceobjects.com/ain/api.svc/JSON/GetAddressInsight?BusinessName={BUSINESSNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&Zip={ZIP}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

XML:
- https://trial.serviceobjects.com/ain/api.svc/XML/GetAddressInsight?BusinessName={BUSINESSNAME}&Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&Zip={ZIP}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

GetAddressInsight Inputs

Name	Type	Description
BusinessName	String	A company name for a business, can provide additional insight to the location or append a SuiteLink value
Address1	String	The address line 1 of the contact or business address.
Address2	String	The address line 2 of the contact or business address.
City	String	The city of the address to validate. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required.
State	String	The state of the address to validate. For example, “NY”. This does not need to be contracted, full state names will work as well. The state isn’t required, but if one is not provided, the Zip code is required.
Zip	String	The zip code of the address to validate. A zip code isn’t required, but if one is not provided, the City and State are required.
TestType	String	Currently blank or ‘census_loose’. ‘census_loose’ provides a best possible match based on census data. More test types to come in the future.
LicenseKey	String	Your license key to use the service. This is a required value. Sign up for a free trial key at https://www.serviceobjects.com/address-insight/.

GetAddressInsight Outputs

AddressInsightResponse

Name	Type	Values	Description
Status	String	Varies	An overall human readable description of the result of the set of validations. This result may change over time and is designed to provide a quick overview of the results, not meant for programming against.
StatusScore	String	0-100	A 0-100 score representing the percent likelihood that the location is a good one.
AddressStatus	String	Success/Fail	An indicator of how the location fared as it pertains to address validation.
DPV ^[1]	String	1-4	Number that correlates to a DPV (Delivery Point Validation) result. An indicator displaying whether or not the address is recognized as deliverable by the USPS.
DPVDesc	String	Varies	Human readable description of the DPV result.
Address	String	Varies	The corrected and standardized first line of the given address.
AddressExtra	String	Varies	Extraneous input address information that is NOT part of the standardized address but may provide extra insight.
City	String	Varies	The corrected and standardized city of the given address.
State	String	2 character code (XX)	The corrected and standardized state of the given address.
Zip	String	9 digit number(XXXXX-XXXX)	The corrected and standardized nine digit zip code of the given address.
BarcodeDigits ^[2]	String	12 digit number	The twelve digit post office delivery barcode digits.
CarrierRoute	String	4 character code (XXXX)	4 chars: 1 for the route type, 3 for the route code. Identifies a group of addresses when prepended by 5-digit Zip.
CongressCode	String	XX	The congress code of the given address.
CountyName	String	Varies	The county name of the given address.
FragmentHouse	String	Varies	The parsed house number of the given address.
FragmentPreDir	String	N,S,E,W, NW,NE,SW,SE	The parsed pre-directional of the address’s street. “North” in “North Main St West”.
FragmentStreet	String	Varies	The parsed name of the street in the given address. “Main” in “North Main St West”.
FragmentSuffix	String	Varies	The parsed suffix of the street in the given address. “St” in “North Main St West”.
FragmentPostDir	String	N,S,E,W, NW,NE,SW,SE	The parsed post-directional of the address’s street. “West” in “North Main St West”.
FragmentUnit	String	Varies	The parsed type of the apartment, box, unit, etc. “Apt” in “Main St, Apt B”
FragmentUnitNumber	String	Varies	The parsed apartment, box, unit, etc. number of the given address. “B” in “Main St, Apt B”
FragmentPMBPrefix	String	Varies	The parsed type of personal mail box. “PMB” in “Main St, Apt B PMB 150”
FragmentPMBNumber	String	Varies	The parsed number of the personal mailbox. “150” in “Main St, Apt B PMB 150”
Corrections	String	Varies	Number that correlates to a Corrections Description. Service Objects may add or change Correction descriptions, but will never modify existing codes.
CorrectionsDesc	String	Varies	Description of what was corrected in an address. Service Objects may add or change Correction descriptions, but will never modify existing codes.
AddressNotes	String	Varies	A comma separated string of numbers representing informative findings about the address as it pertains to Address Validation. See AddressNotes table below for more detailed description.
AddressNotesCodes	String	Varies	A comma separated string of human readable descriptions for the AddressNotes. See AddressNotes table below for more detailed description.
GeocodeStatus	String	Success/Fail	An indicator of how the location fared as it pertains to the geolocation of said location.
LocationLatitude	String	Decimal Number	The closest geocoding latitude match of the given address. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. See GeocodeNotes for levels.
LocationLongitude	String	Decimal Number	The closest longitude match of the given address. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. See GeocodeNotes
CensusTract	String	6 digit decimal (XXXX.XX)	The Census Tract of the given address.
CensusBlock	String	4 digit number (XXXX)	The Census Block of the given address.
PlaceName	String	Varies	The PlaceName of the location as it pertains to geolocation. May be more exact than USPS returned City information as those designations exist to ease postal deliveries and not to return precise results.
ClassFP	String	Alpha-Numeric (XX)	A code that defines the current class of the geographic location.
SLDUST	String	Varies	Current state legislative district upper (senate) chamber code.
SLDLST	String	Varies	Current state legislative district lower (house) chamber code
CountyFIPS	String	3 digit number (XXX)	County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US.
StateFIPS	String	2 digit number (XX)	State FIPS(Federal Information Processing Standard) code; used to uniquely identity states
GeocodeNotes	String	Varies	A comma separated string of numbers representing informative findings about the address as it pertains to Location Geocoding. See GeocodeNotes table below for more detailed description.
GeocodeNotesCodes	String	Varies	A comma separated string of human readable descriptions for the GeocodeNotes. See GeocodeNotes table below for more detailed description.
ZipStatus	String	Success/Fail	An indidcator of success in returning demographics/census data for the given zip code.
ZipLatitude	String	Number	A zip centroid Latitude.
ZipLongitude	String	Number	A zip centroid Longitude.
CityType	String	N, P, U, B, A, C, S, K	The city type of the given zip code. The code refers to the type of postal station in a given zip code. See table below for descriptions for each of the codes.
CityAliasName	String	Varies	A common alternative city name for the given location.
AreaCode	String	Varies	Contains one or more area codes associated with the zip code. e.g. zip code: 74570 has 4 and will return: “918/405/539/580”
TimeZone	String	1 digit number (X)	The number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc.
DaylightSaving	String	Y or N	Whether the given zip code observes DayLight Savings time.
MSA	String	Varies	The Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core.
CBSA	String	Varies	The Core Based Statistical Area Code. A code used to identify an urban center of at least 10,000 people and adjacent areas that are socioeconomically tied to the urban center.
CBSA_Div	String	Varies
PMSA	String	Varies	The Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center.
DMA	String	Varies	The Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs.
ZipHouseholdValue	String	Number	Average value of houses in the zip code
ZipPersonsPerHousehold	String	Number	Average number of persons per household in the zip code
ZipHouseholdIncome	String	Number	Average Income per household in the zip code
CountyHouseholdIncome	String	Number	Average Income per household in the country of the zip code
StateHouseholdIncome	String	Number	Average Income per household in the state of the zip code
ZipNotes	String		A comma separated string of numbers representing informative findings about the zip code. See ZipNotes table below for more detailed description.
ZipNotesCodes	String		A comma separated string of human readable descriptions for the ZipNotes. See ZipNotes table below for more detailed description.
Error	Error	Varies	The error object containing information about the error returned.

* Indicates that the output value is coming soon.

References

1.^ CASS and DPV: A Higher Standard for Address Accuracy

2.^ Address Deduplication Using USPS Barcodes