# Chapter 4.4.3.1 - Geocode Jurisdiction Determination Source: https://developer.avalara.com/products/communications/integration-guides/dev-guide_rest_v2/customizing-transactions/sample-transactions/geocode-jurisdiction-determination/ - [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geocoding-options/) - [Next](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch/) The [`/api/v2/geo/Geocode` Jurisdiction Determination endpoint](/communications/dev-guide_rest_v2/getting-started/environments-endpoints#jur_determine) 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](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/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](/communications/dev-guide_rest_v2/reference/geocode-requests/). Specify a list of [street addresses](#street) or [latitude/longitude coordinate pairs](#lat_long) to geocode. Geocoded results are returned in the [Geocode Result](/communications/dev-guide_rest_v2/reference/geocode-result/). Either a [street address](#street) or [latitude/longitude pair](#lat_long) 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](#street) geocode request. `cass` has no effect on a [latitude/longitude](#lat_long) geocode request and is ignored if set. - `true`: Returns the CASS validated address as part of the [Geocode Result](/communications/dev-guide_rest_v2/reference/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 latitude/longitude: - Both Latitude (`lat`) and Longitude (`long`) are required - Latitude/Longitude geocoding does not return street address results ### The Results The [Geocode Result](/communications/dev-guide_rest_v2/reference/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`). ```json [ { "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](#collapse1) ```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. ```json [ { "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](#collapse2) ```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. ```json [ { "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](#collapse3) ```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. ```json [ { "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](#collapse4) ```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. ```json [ { "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](#collapse5) ```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 }] ``` ### See Also #### Input Objects - [Geocode requests](/communications/dev-guide_rest_v2/reference/geocode-requests/) #### Output Objects - [Geocode result](/communications/dev-guide_rest_v2/reference/geocode-result/) - [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geocoding-options/) - [Next](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch/)