Returns the latitude and longitude for a given US address. This operation will use cascading logic when an exact address match is not found and it will return the next closest level match available. The operation output is designed to allow the service to return new pieces of data as they become available without having to re-integrate.

URL Endpoints

HTTP POST Request Help Page

GetBestMatch_V4 tries to find a match at the most granular level that it can:

  1. Property Match on the street level
  2. Zip + 4 Match
  3. Zip + 3 Match
  4. Zip + 2 Match
  5. Zip + 1 Match
  6. Zip Match
  7. City/State Match (least accurate)

This operation will also return a code indicating the level at which it matched. The codes are:

  1. S – Street Level Property Match
  2. P – Zip plus four match
  3. R – Zip plus three-match
  4. T – Zip plus two match
  5. N – Zip plus one match
  6. Z – Zip level match (zip plus zero)
  7. C – City/state match

GetBestMatches_V4 Inputs

NameTypeDescription
AddressStringAddress line of the address to geocode. For example, “123 Main Street”.
CityStringThe city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required.
StateStringThe state of the address to geocode. 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.
PostalCodeStringThe zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address/address-geocode-us

GetBestMatches_V4 Outputs

NameTypeValuesDescription
Level [1]StringVariesThe level code at which the address matched.
See above for a listing of possible outputs.
LevelDescriptionStringVariesAn explicit description of the level code, described above.
LatitudeStringDecimal Number The latitude of the given address.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point.
LongitudeStringDecimal Number The longitude of the given address.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. 
ZipStringVariesThe corrected zip plus four of the given address.
InformationComponentsInformationComponent array or NULLVariesA name-value pair collection containing additional information about the location. See the InformationComponent table and the list of Components for more details.
ErrorErrorVariesError object indicating why the service could not return a result. See “Errors” below for more information.
NameTypeValuesDescription
NameStringVariesThe component name of the Name-Value pair. Possible examples are “CountyFIPS”, “CensusTract” “CensusGeoID”
ValueStringVariesThe component value of the Name-Value pair.
NameTypeValueDescription
StateFIPSString2 Digit NumberState FIPS(Federal Information Processing Standard) code; used to
uniquely identity states.
StateStringVariesState name.
CountyFIPSString3 Digit NumberCounty FIPS(Federal Information Processing Standard) code; used to
uniquely identify counties across the US.
CountyStringVariesCounty name.
CensusTractString6 Digit
Decimal Number
The census tract of the given address.
A census tract is a statistical subdivision of a county.
CensusBlockString4 Digit NumberThe census block of the given address.
A block is the smallest geographic unit used by the US Census.
CensusGeoIDString15 Digit NumberA Census based geographic identification code that uniquely identifies a geographic statistical area.
ClassFPStringAlpha-NumericA code that defines the current class of the geographic location.
CongressCodeStringVariesThe congressional district number.
SLDUSTStringVariesCurrent state legislative district upper (senate) chamber code.
SLDLSTStringVariesCurrent state legislative district lower (house) chamber code
PlaceNameStringVariesThe name of the place that the coordinates are associated with. Most commonly the name of a municipality, city, town, village, or community.

NOTICE: For street-level property matches the place name will reflect the name of the area where the exact coordinates reside. Coordinates for some unincorporated areas lie outside of known city/community boundaries. In this case the place name will reflect the name of the place that the address is associated with, which is most commonly derived from USPS postal data.
IsUnincorporated [2]StringVariesIndicates if the coordinates are for an unincorporated area. Only appears for street-level property matches (S).

1 – Indicates that the coordinates fall within the boundaries of a known unincorporated area.
2 – Indicates that the coordinates fall outside of the boundaries of a known area.
TimeZone_UTCStringVariesThe time zone is in UTC offset format.
GoogleMapsURLStringVariesGoogle Maps URL with the coordinates to the location.
BingMapsURLStringVariesBing Maps URL with the coordinates to the location.
MapQuestURLStringVariesMap Quest URL with the coordinates to the location.

References

  1. Understanding Geographic Data in DOTS Address Geocode US
  2. How to Identify Incorporated and Unincorporated Places in the United States