Avalara Developer Network Developer communications

Chapter 4.4.2 - Geocode Jurisdiction Determination

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.

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 Result
  • false: 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)


Considerations when using street address:

  • 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 street address:

  • 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:
  • Street address (addr)
  • City (city)
  • State (st)
  • Postal Code (zip)

CASS is not returned for latitude/longitude requests
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
  • true: The address is incorporated, meaning it is within city limits
  • false: The address in unincorporated (not in 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) is 1.01
  • Census Block Group (cBlk) and Census Tract (cTrc) are both 0
  • 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.

View the Response JSON
[
  {
    "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.

View the Response JSON
[
  {
    "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.

View the Response JSON
[
  {
    "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.

View the Response JSON
[
  {
    "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)

View the Response JSON
[
  {
    "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
  }
]