# Chapter 4.4.3.2 - Geo Batch

Source: https://developer.avalara.com/products/communications/integration-guides/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch/

-   [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geocode-jurisdiction-determination/)
-   [Next Chapter](/communications/dev-guide_rest_v2/reference/)

Communications Geo Batch accepts an input address or latitude/longitude file and returns a link to an output file containing the geocoded results.

To use Geo Batch:

-   [Upload](#upload) a CSV containing your address or latitude/longitude geocoding requests
-   Download and export the results to your database using the [Status](#status) endpoint
-   View the [logs](#log) related to the processing of a file

When to use [Geo Batch](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch/):

-   You have a high volume of address or latitude/longitude geocoding requests
-   You perform bill runs on a regular basis
-   You are interested in importing your response file into a spreadsheet or a database
-   A backup of the input and output data is needing to be stored in the AvaTax for Communications platform
-   An immediate response for your batch files isn't needed

#### Note

The Geocode Jurisdiction Determination endpoints support 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.

### Upload

The `/api/v2/geo/batch/upload` endpoint accepts formData upload of a CSV input file. Provide a list of [street addresses](#street) or [latitude/longitude coordinate pairs](#lat_long) to geocode. A processId is returned in the [Geo Batch Submit File Response](/communications/dev-guide_rest_v2/reference/geo-batch-submit-file-response/).

Either a list of [street addresses](#street) or [latitude/longitude pairs](#lat_long) can be specified in CSV, but an input file can’t contain a mixture of both street address and latitude/longitude pairs. Be sure to include these **required** items in each CSV:

-   Header row - used by Geo Batch to determine if the file is an address or latitude/longitude file
-   Identifier column - used to tie the requested address to the result

The CSV file doesn’t have a set naming convention, and doesn’t need to specify Address or Latitude/Longitude in the file name.

#### Street Address Data

Create a CSV using one or more of these address fields:

-   Identifier (`Identifier`)
-   Street address (`StreetAddress`)
-   City (`City`)
-   State (`State`)
-   Postal Code (`Zip`)

**Considerations when using street address**:

-   One of the following is required when geocoding a street address:

-   City (`City`) and State (`State`)
-   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

**Sample Input Address CSV**

Identifier,StreetAddress,City,State,Zip  
1,8675 west 96th St suite 220,Overland Park, KS,66212  
2,8675 west 96th St suite 220,Overland Park, KS,66212-3382  
4,1600 Pennsylvania Ave,Washington DC,DC,20500  
3,1600 Pennsylvania Ave,Washington DC,DC,20500  

#### Latitude/Longitude Data

Create a CSV using one or more of these address fields:

-   Identifier (`Identifier`)
-   Latitude (`Latitude`)
-   Longitude (`Longitude`)

Considerations when using latitude/longitude:

-   Both Latitude (`Latitude`) and Longitude (`Longitude`) are required
-   Latitude/Longitude geocoding does not return street address results

**Sample Input Latitude/Longitude CSV**

Identifier,Latitude,Longitude  
312254, 34.08, -117.89   
376009, 34.08, -87.06  

#### Upload Results

The [Geo Batch Submit File Response](/communications/dev-guide_rest_v2/reference/geo-batch-submit-file-response/) returns a Process Id (`ProcessId`) to be used in both the [Status](#status) and [Log](#log) endpoints.

### Status

Pass the Process Id (`ProcessId`) returned during the [Geo Batch Upload](#upload) to the Status endpoint (`/api/v2/geo/batch/status/{processId}`) to retrieve the status of the input file. The [Geo Batch Status](/communications/dev-guide_rest_v2/reference/geo-batch-status/) endpoint returns status details and links to download both the input and output files:

-   Requested (`RequestDate`), Processing Start (`ProcessingStart`), and Processing End (`ProcessingEnd`) dates
-   Status of the request (`Status`)
-   Input file name (`InputFile`) and a download link for the input file (`InputFileDownload`)
-   Output file name (`OutputFile`) and a download link for the output file (`OutputFileDownload`)

The file download links expire after 60 seconds, so be sure to re-submit a request to the Status endpoint (`/api/v2/geo/batch/status/{processId}`) each time a copy of the file is needed. There isn’t a limit to how often the links can be retrieved via the `Status` endpoint.

### Log

Pass the Process Id (`ProcessId`) returned during the [Geo Batch Upload](#upload) to the Log endpoint (`/api/v2/geo/batch/log/{processId}`) to retrieve the log creating during the Geo Batch processing. The [Geo Batch Log](/communications/dev-guide_rest_v2/reference/geo-batch-log/) returns processing details of each step:

-   Date of the log (`Date`)
-   Status of the step (`Status`)
-   The message (`Message`) returned from Geo Batch

Look in the Log for specific error messaging related to failed Geo Batch processing.

### Results File

The results file is saved to a Zip file (“input file name”\_output.zip.) with the naming convention of “input file name”\_output.csv. The data returned depends on the type of input file: address or latitude/longitude.

Match the results row to the input row using the Identifer column.

#### Address Results

The Address Geo Batch output CSV contains the following fields:

Column

Name

Description

`Identifier`

Identifier

Identifer from the input file used to tie the request to the result

`Score`

Score

A percentage, represented as a decimal, indicating the accuracy of the address match in the mapping database

`PCode`

PCode

PCode for the taxing jurisdiction

`JurisdictionName`

Taxing jurisdiction name

Name of the taxing jurisdiction related to the returned PCode

`FipsCode`

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  

`Unincorporated`

Unincorporated

Indicates if the address is within city limits

-   `0`: The address is incorporated, meaning it is within city limits
-   `1`: The address in unincorporated (not in city limits)

`County`

County

County name of geocoded jurisdiction

`Latitude`

Latitude

Latitude of the matching jurisdiction

`Longitude`

Longitude

Longitude of the matching jurisdiction

`StreetAddress`

Street Address

Street Address of the requested address

`City`

City

City of the requested address

`State`

State

State of the requested address

`Zip`

Postal Code

Postal Code of the requested address

`CassAddress`

CASS Street Address

CASS validated street address

`CassCity`

CASS City

CASS validated city

`CassState`

CASS State

CASS validated state

`CassZip`

CASS Postal Code

CASS validated postal code

`FeatureID`

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

`CensusTract`

Census Tract

ID of the contiguous group of census block groups, geocoded based on census data

`CensusBlockGroup`

Census Block Group

ID of the smallest area surrounded by streets, geocoded based on census data

**Sample Output Address CSV**

Identifier,Score,PCode,JurisdictionName,FipsCode,Unincorporated,County,Latitude,Longitude,StreetAddress,City,State,Zip,CassAddress,CassCity,CassState,CassZip,FeatureID,CensusTract,CensusBlockGroup  
1,1,1248900,OVERLAND PARK,2009153775,0,JOHNSON,38.9541512904661,-94.6848609769671,8675 W 96TH ST STE 220,OVERLAND PARK,KS,66212-3382,8675 W 96TH ST STE 220,OVERLAND PARK,KS,66212-3382,485639,51804,1014  
2,1,1248900,OVERLAND PARK,2009153775,0,JOHNSON,38.9541512904661,-94.6848609769671,8675 W 96TH ST STE 220,OVERLAND PARK,KS,66212-3382,8675 W 96TH ST STE 220,OVERLAND PARK,KS,66212-3382,485639,51804,1014  
4,0.743033151626587,534000,WASHINGTON,1100150000,0,WASHINGTON DC,38.8987189314404,-77.0365450000052,1600 PENNSYLVANIA AVE NW,WASHINGTON,DC,20502-0003,1600 PENNSYLVANIA AVE NW,WASHINGTON,DC,20500-0003,2390665,6202,1031  
3,0.743033151626587,534000,WASHINGTON,1100150000,0,WASHINGTON DC,38.8987189314404,-77.0365450000052,1600 PENNSYLVANIA AVE NW,WASHINGTON,DC,20502-0003,1600 PENNSYLVANIA AVE NW,WASHINGTON,DC,20500-0003,2390665,6202,1031  

#### Latitude/Longitude Results

The Latitude/Longitude Geo Batch output CSV contains the following fields:

Column

Name

Description

`Identifier`

Identifier

Identifer from the input file used to tie the request to the result

`Latitude`

Latitude

Latitude of the matching jurisdiction

`Longitude`

Longitude

Longitude of the matching jurisdiction

`Country`

Country

Country of the requested latitude/longitude

`State`

State

State of the requested latitude/longitude

`City`

City

City of the requested latitude/longitude

`County`

County

County of the requested latitude/longitude

`PCode`

PCode

PCode for the taxing jurisdiction

`FeatureID`

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

**Sample Output Latitude/Longitude CSV**

Identifier,Latitude,Longitude,Country,State,City,County,PCode,FeatureID  
312254,34.08,-117.89,USA,CA,LOS ANGELES,COVINA,299700,2410251  
376009,34.08,-87.06,USA,AL,CULLMAN,CULLMAN COUNTY,24100,161547  

### See Also

#### Output Objects

-   [Geo Batch Submit File Response](/communications/dev-guide_rest_v2/reference/geo-batch-submit-file-response/)
-   [Geo Batch Status](/communications/dev-guide_rest_v2/reference/geo-batch-status/)
-   [Geo Batch Download Response](/communications/dev-guide_rest_v2/reference/geo-batch-download-response/)
-   [Geo Batch Log](/communications/dev-guide_rest_v2/reference/geo-batch-log/)
-   [Geo Batch Log Item](/communications/dev-guide_rest_v2/reference/geo-batch-log-item)

-   [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geocode-jurisdiction-determination/)
-   [Next Chapter](/communications/dev-guide_rest_v2/reference/)