The /api/v2/geo/Geocode Jurisdiction Determination endpoint returns a list of geocoded results.
Note
The Geocode Jurisdiction Determination endpoint supports geocoding for US, Puerto Rico, and other US territories. Addresses and coordinate pairs in foreign countries, including Canada and Mexico, are not supported and do not return results.
Use Geo Batch for high-volume geocoding requests.
- Upload a CSV containing your address or latitude/longitude geocoding requests
- Download and export the results to your database
Geocode Jurisdiction Determination
The Geocode Jurisdiction Determination endpoint accepts a list of Geocode Requests. Specify a list of street addresses or latitude/longitude coordinate pairs to geocode. Geocoded results are returned in the Geocode Result.
Either a street address or latitude/longitude pair can be specified in each individual request, but a list of geocode requests can contain a mixture of both street address and latitude/longitude pairs.
Reference ID
The Reference ID (ref) is used to tie the requested address or lat/long to the result. The Reference ID is useful when a large list of geocoded results are requested.
CASS
Use the CASS flag (cass) to indicate if the CASS validated address should be returned on a street address geocode request. cass has no effect on a latitude/longitude geocode request and is ignored if set.
true: Returns the CASS validated address as part of the Geocode Resultfalse: The CASS validated address is not included in the results
Street Address Data
Specify a street address using one or more of these fields:
- Street address (
addr) - City (
city) - State (
st) - Postal Code (
zip)
- One of the following is required when geocoding a street address:
- City (
city) and State (st) - Postal Code (
zip) - Street address should normally begin with a numeric street number. The exception is that there are certain states that allow a 1-letter prefix on the street, such as "G4386 S Saginaw St"
- Post Office (PO) Box addresses are not supported in geocoding because a PO Box does not accurately reflect a taxing jurisdiction
Latitude/Longitude Data
Specify a latitude/longitude coordinate pair using Latitude (lat) and Longitude (long).
Considerations when using latitude/longitude:
- Both Latitude (
lat) and Longitude (long) are required - Latitude/Longitude geocoding does not return street address results
The Results
The Geocode Result contains the following fields:
| Key | Name | Description |
|---|---|---|
ref | Reference ID | Reference ID from the geocode request used to tie the request to the result |
cass | CASS Address Information | CASS validated address information including:
|
cBlk | Census Block Group | ID of the smallest area surrounded by streets, geocoded based on census data Census Block Group is always 0 for latitude/longitude requests |
cTrc | Census Tract | ID of the contiguous group of census block groups, geocoded based on census data Census Tract is always 0 for latitude/longitude requests |
cnty | County | County name of geocoded jurisdiction |
feat | Feature ID | The Geographic Names Information System (GNIS) feature id is a unique, permanent geographic feature identifier assigned by the U.S. Board on Geographic Names |
fips | FIPS Code | 10-digit number in the format of SSCCCPPPPP where SS = State Code, CCC = County Code and PPPPP = Place Code. FIPS codes that start with a “99” in the state position are Avalara-defined codes for special tax jurisdictions |
inc | Incorporated | Indicates if the address is within city limits
|
jur | Taxing jurisdiction name | Name of the taxing jurisdiction related to the returned PCode |
lat | Latitude | Latitude of the matching jurisdiction |
long | Longitude | Longitude of the matching jurisdiction |
pcd | PCode | PCode for the taxing jurisdiction |
scr | Score | A percentage, represented as a decimal, indicating the accuracy of the address match in the mapping database |
Fallback
The Fallback process is used when a match can’t be found in the geocoding database and, instead, a match is found based on the Postal Code (zip) and city name (city).
Characteristics of a Fallback response:
- Score (
scr) is1.01 - Census Block Group (
cBlk) and Census Tract (cTrc) are both0 - Latitude (
lat) and Longitude (long) are both-1
Geocode Jurisdiction Determination Example 1 - Street Address
This example demonstrates a geocoding request for a street address. The CASS validated address is being requested (cass is true).
[ { "ref": "Street Address Geocode", "cass": true, "addr": "255 South King St", "city": "Seattle", "st": "WA", "zip": "98104" }]Response
The street address is successfully geocoded with a score (scr) of 1.
[ { "ref": "Street Address Geocode", "cass": { "addr": "255 S KING ST ", "city": "SEATTLE", "st": "WA", "zip": "98104-2832" }, "cBlk": 2016, "cTrc": 9300, "cnty": "KING", "feat": 2411856, "fips": "5303363000", "inc": true, "jur": "SEATTLE", "lat": 47.59826893144039, "long": -122.33089769285252, "pcd": 4133800, "scr": 1 }]Geocode Jurisdiction Determination Example 2 - Latitude/Longitude Pair
This example geocodes a latitude/longitude coordinate pair.
[ { "ref": "Lat/Long Geocode", "lat": 35.991130741436415, "long": -78.90267307450108 }]Response
The latitude/longitude coordinate pair is successfully geocoded with a score (scr) of 0.9999.
[ { "ref": "Lat/Long Geocode", "cBlk": 0, "cTrc": 0, "cnty": "DURHAM", "feat": 2403521, "fips": "3706319000", "inc": true, "jur": "DURHAM", "lat": 35.991130741436415, "long": -78.90267307450108, "pcd": 2757800, "scr": 0.9999689324056225 }]Geocode Jurisdiction Determination Example 3 - Street Address and Latitude/Longitude Pair
This example shows how to send multiple geocode requests. One request is a street address while the other is a latitude/longitude coordinate pair.
[ { "ref": "Street Address Geocode", "cass": true, "addr": "255 South King St", "city": "Seattle", "st": "WA", "zip": "98104" }, { "ref": "Lat/Long Geocode", "lat": 35.991130741436415, "long": -78.90267307450108 }]Response
Two geocoded results are returned. Use the Reference ID (ref) to match the result to the request.
[ { "ref": "Street Address Geocode", "cass": { "addr": "255 S KING ST ", "city": "SEATTLE", "st": "WA", "zip": "98104-2832" }, "cBlk": 2016, "cTrc": 9300, "cnty": "KING", "feat": 2411856, "fips": "5303363000", "inc": true, "jur": "SEATTLE", "lat": 47.59826893144039, "long": -122.33089769285252, "pcd": 4133800, "scr": 1 }, { "ref": "Lat/Long Geocode", "cBlk": 0, "cTrc": 0, "cnty": "DURHAM", "feat": 2403521, "fips": "3706319000", "inc": true, "jur": "DURHAM", "lat": 35.991130741436415, "long": -78.90267307450108, "pcd": 2757800, "scr": 0.9999689324056225 }]Geocode Jurisdiction Determination Example 4 - Street Address with Fallback
This example demonstrates the Fallback process. A valid city (city), state (st), and Postal Code (zip) are used, but the street address (addr) is invalid.
[ { "ref": "Fallback Request", "cass": true, "addr": "123 Fake St", "city": "New York", "st": "NY", "zip": "10003" }]Response
A Fallback result is returned, indicated by the score (scr) being 1.01.
[ { "ref": "Fallback Request", "cBlk": 0, "cTrc": 0, "cnty": "NEW YORK", "feat": 2083394, "fips": "3606102275", "inc": true, "jur": "NEW YORK", "lat": -1, "long": -1, "pcd": 2604100, "scr": 1.01 }]Geocode Jurisdiction Determination Example 5 - Unincorporated Street Address
This request contains a geocode request for an unincorporated address.
[ { "ref": "Unincorporated Street Address", "cass": true, "addr": "24210 E 19th Ave", "city": "Aurora", "st": "CO", "zip": "80019" }]Response
The returned geocoded address is unincorporated (inc is false)
[ { "ref": "Unincorporated Street Address", "cass": { "addr": "24210 E 19TH AVE ", "city": "AURORA", "st": "CO", "zip": "80019-3706" }, "cBlk": 1143, "cTrc": 8353, "cnty": "ADAMS", "feat": 198116, "fips": "9900429801", "inc": false, "jur": "AURORA RTD", "lat": 39.743492290111995, "long": -104.70495125456084, "pcd": 429801, "scr": 0.98 }]