Page tree
Skip to end of metadata
Go to start of metadata


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

Not currently used - May allow future customizations

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/products/address-geocoding/address-insight.


GetAddressInsight Outputs


AddressInsightResponse

Name

Type

Values

Description

StatusStringVariesAn 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.
StatusScoreString0-100A 0-100 score representing the percent likelihood that the location is a good one.
AddressStatusStringSuccess/FailAn indicator of how the location fared as it pertains to address validation.
String1-4Number that correlates to a DPV (Delivery Point Validation) result. An indicator displaying whether or not the address is recognized as deliverable by the USPS.
DPVDescStringVariesHuman readable description of the DPV result.
AddressStringVariesThe corrected and standardized first line of the given address.
AddressExtraStringVariesExtraneous input address information that is NOT part of the standardized address but may provide extra insight.
CityStringVariesThe corrected and standardized city of the given address.
StateString2 character code (XX)The corrected and standardized state of the given address.
ZipString9 digit number(XXXXX-XXXX)The corrected and standardized nine digit zip code of the given address.

BarcodeDigits [2]

String12 digit numberThe twelve digit post office delivery barcode digits.
CarrierRouteString4 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.
CongressCodeStringXXThe congress code of the given address.
CountyNameStringVariesThe county name of the given address.
FragmentHouseStringVariesThe parsed house number of the given address.
FragmentPreDirStringN,S,E,W, NW,NE,SW,SEThe parsed pre-directional of the address's street. "North" in "North Main St West".
FragmentStreetStringVariesThe parsed name of the street in the given address. "Main" in "North Main St West".
FragmentSuffixStringVariesThe parsed suffix of the street in the given address. "St" in "North Main St West".
FragmentPostDirStringN,S,E,W, NW,NE,SW,SEThe parsed post-directional of the address's street. "West" in "North Main St West".
FragmentUnitStringVaries

The parsed type of the apartment, box, unit, etc. "Apt" in "Main St, Apt B"

FragmentUnitNumberStringVariesThe parsed apartment, box, unit, etc. number of the given address. "B" in "Main St, Apt B"
FragmentPMBPrefixStringVariesThe parsed type of personal mail box. "PMB" in "Main St, Apt B PMB 150"
FragmentPMBNumberStringVariesThe parsed number of the personal mailbox. "150" in "Main St, Apt B PMB 150"
CorrectionsStringVariesNumber that correlates to a Corrections Description. Service Objects may add or change Correction descriptions, but will never modify existing codes.
CorrectionsDescStringVariesDescription of what was corrected in an address. Service Objects may add or change Correction descriptions, but will never modify existing codes.
AddressNotesStringVariesA 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.
AddressNotesCodesStringVariesA comma separated string of human readable descriptions for the AddressNotes. See AddressNotes table below for more detailed description.
GeocodeStatusStringSuccess/FailAn indicator of how the location fared as it pertains to the geolocation of said location.
LocationLatitudeStringDecimal 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.

LocationLongitudeStringDecimal 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

CensusTractString6 digit decimal (XXXX.XX)The Census Tract of the given address.
CensusBlockString4 digit number (XXXX)

The Census Block of the given address.

PlaceNameStringVariesThe 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.
ClassFPStringAlpha-Numeric (XX)A code that defines the current class of the geographic location.
SLDUSTStringVariesCurrent state legislative district upper (senate) chamber code.
SLDLSTStringVariesCurrent state legislative district lower (house) chamber code
CountyFIPSString3 digit number (XXX)County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US.
StateFIPSString2 digit number (XX)State FIPS(Federal Information Processing Standard) code; used to uniquely identity states 
GeocodeNotesStringVariesA 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.
GeocodeNotesCodesStringVariesA comma separated string of human readable descriptions for the GeocodeNotes. See GeocodeNotes table below for more detailed description.
ZipStatusStringSuccess/FailAn indidcator of success in returning demographics/census data for the given zip code.
ZipLatitudeStringNumberA zip centroid Latitude.
ZipLongitudeStringNumberA zip centroid Longitude.
CityTypeStringN, P, U, B, A, C, S, KThe 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.
CityAliasNameStringVariesA common alternative city name for the given location.
AreaCodeStringVariesContains one or more area codes associated with the zip code. e.g. zip code: 74570 has 4 and will return: "918/405/539/580"
TimeZoneString1 digit number (X)The number of hours offset from GMT. 5 = Eastern time zone, 8 = Pacific time zone, etc.
DaylightSavingStringY or N

Whether the given zip code observes DayLight Savings time.

MSAStringVariesThe Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core.
CBSAStringVariesThe 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_DivStringVaries
PMSAStringVariesThe Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center. 
DMAStringVariesThe Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs. 
ZipHouseholdValueStringNumberAverage value of houses in the zip code
ZipPersonsPerHouseholdStringNumberAverage number of persons per household in the zip code
ZipHouseholdIncomeStringNumberAverage Income per household in the zip code
CountyHouseholdIncomeStringNumberAverage Income per household in the country of the zip code
StateHouseholdIncomeStringNumberAverage Income per household in the state of the zip code
ZipNotesString
A comma separated string of numbers representing informative findings about the zip code. See ZipNotes table below for more detailed description.
ZipNotesCodesString
A comma separated string of human readable descriptions for the ZipNotes. See ZipNotes table below for more detailed description.
ErrorErrorVariesThe 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


  • No labels