Chapter 4.4.3.2 - Geo Batch

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 a CSV containing your address or latitude/longitude geocoding requests
  • Download and export the results to your database using the Status endpoint
  • View the logs related to the processing of a file

When to use 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 or latitude/longitude coordinate pairs to geocode. A processId is returned in the Geo Batch Submit File Response.

Either a list of street addresses or latitude/longitude pairs 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 returns a Process Id (ProcessId) to be used in both the Status and Log endpoints.

Status

Pass the Process Id (ProcessId) returned during the Geo Batch Upload to the Status endpoint (/api/v2/geo/batch/status/{processId}) to retrieve the status of the input file. The 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 to the Log endpoint (/api/v2/geo/batch/log/{processId}) to retrieve the log creating during the Geo Batch processing. The 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

PreviousNext