Geocoding Services

Web Application Programming Interface (API)

Last updated 07/2021
______________________________________________________________________________

Contents
Geocoding Definition............................................................................................................................... 1
Audience ................................................................................................................................................. 1
Single Record Geocoding Service Requests .............................................................................................. 1
Required Parameters ........................................................................................................................... 2
Optional Parameters ........................................................................................................................... 2
Geocoding Service Responses .................................................................................................................. 3
JSON Output Format............................................................................................................................ 3
Batch Geocoding ..................................................................................................................................... 5
Required Parameters ........................................................................................................................... 6
Example Shell Script Submission .......................................................................................................... 6
Geocoding Definition
Geocoding is the process of taking an address and returning an actual or calculated latitude/longitude
coordinate. Depending on the parts of the address that are provided, determines to what granularity it
is possible to geocode.

The current Geocoding Services engine requires a structure address be provided. The resulting lat/long
is calculated along an address range.

There are two entry points for the geocoding service – single record submission and batch.

The acceptable input address parts are:

• Structure number and street name (required)

• City name (optional)
• State (optional)
• ZIP code (optional)

The single record service allows for all of these parts to be submitted in a single line, or as separate
fields. The batch requires each field to exist (either with text or blank) in a delimited form, preceded by
a unique ID.

Audience
This document is intended for application, website, and mobile developers within the U.S. Census
Bureau and the general public who want to leverage the Geocoding Services capability.

This service is designed for coding a provided address, or file of addresses, to a latitude/longitude
coordinate based on data that’s been loaded into the geocoding engine from a MAF/TIGER benchmark
database.

The optional inclusion of the Geographic Lookup (geoLookup) adds information to the result relating to
various levels of geography that cover the aforementioned latitude/longitude coordinate. GeoLookup
results can also be obtained directly by searching on the latitude/longitude coordinates.

Single Record Geocoding Service Requests

A Geocoding Service API request must be in the following form:

https://geocoding.geo.census.gov/geocoder/returntype/searchtype?parameters

1
Required Parameters
• returntype – locations (to get just geocoding response) or geographies (to get geocoding
response as well as geoLookup)
• searchtype – onelineaddress OR address OR coordinates
• benchmark – A numerical ID or name that references what version of the locator should be
searched. This generally corresponds to MTDB data which is benchmarked twice yearly. A full
list of options can be accessed at https://geocoding.geo.census.gov/geocoder/benchmarks. The
general format of the name is DatasetType_SpatialBenchmark. The valid values for these
include:
o DatasetType
▪ Public_AR
o SpatialBenchmark
▪ Current
▪ ACS2021
▪ Census2020
So a resulting benchmark name could be “Public_AR_Current”, “Public_AR_ACS2021”, etc. Over
time, there will always be a “Current” benchmark. It will change as the underlying dataset
changes.
• vintage – a numerical ID or name that references what vintage of geography is desired for
the geoLookup (only needed when returntype = geographies). A full list of options for a given
benchmark can be accessed at
https://geocoding.geo.census.gov/geocoder/vintages?benchmark=benchmarkId. The general
format of the name is GeographyVintage_SpatialBenchmark. The SpatialBenchmark variable
should always match the same named variable in what was chosen for the benchmark
parameter. The GeographyVintage can be Current, ACS2021, etc. So a resulting vintage name
could be “ACS2021_Current”, “Current_ACS2021”, etc. Over time, there will always be a
“Current” vintage. It will change as the underlying dataset changes.
• address (searchtype = onelineaddress) – A single line containing the full address
to be searched
OR
• street, city, state, zip (searchtype = address) – The address split into
the parts indicated. Not all parts need to be specified.
• x,y (searchtype = coordinates) – The longitude and latitude represented as
decimal x/y values. Only returns geoLookup data. Can only be used with returntype =
geographies.

Optional Parameters
• format – The format to be used for returning the standardized output (json, html).
• layers – By default, State, County, Tract, and Block layers are displayed when “geographies”
is the chosen returntype. If additional or different layers are desired, they can be specified in a
comma delimited list by ID or name as listed in the TigerWeb WMS layers, for instance here:

2
 https://tigerweb.geo.census.gov/ArcGIS/rest/services/TIGERweb/tigerWMS_Current/MapServe
r
a valid entry could be: layers=14,16,18 OR layers=Unified School Districts,Secondary School
Districts,Elementary School Districts. Only layers without the word “Labels” are considered. If
all layers are desired, layers=all is an accepted entry.
In cases where the SpatialBenchmark selected is Census2020, the TIGERweb WMS needed is:
https://tigerweb.geo.census.gov/ArcGIS/rest/services/Census2020/tigerWMS_Census2020/Map
Server

Geocoding Service Responses

Geocoding Services responses are returned in the format indicated by the format parameter value in
the URL request’s path.

JSON Output Format

In this example, Geocoding Services API requests a json response for the address “4600 Silver Hill Rd,
Washington, DC 20233”:

https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?address=4600+Silver+Hil
l+Rd%2C+Washington%2C+DC+20233&benchmark=2020&format=json

Other valid examples:

https://geocoding.geo.census.gov/geocoder/locations/address?street=4600+Silver+Hill+Rd&city
= Washington&state=DC&zip=20233&benchmark=Public_AR_Census2020&format=json

https://geocoding.geo.census.gov/geocoder/locations/address?street=4600+Silver+Hill+Rd&city
=Washington&state=DC&benchmark=2020&format=json

The JSON returned by this request is shown below. Note the actual JSON may contain less whitespace.
You should not make assumptions about the amount or format of whitespace in requests.

{"result": {
"input": {
"address": {"address": "4600 Silver Hill Rd, Washington, DC 20233"},
"benchmark": {
"isDefault": false,
"benchmarkDescription": "Public Address Ranges - Census 2020 Benchmark",
"id": "2020",
"benchmarkName": "Public_AR_Census2020"

3
 }
},
"addressMatches": [{
"tigerLine": {
"side": "L",
"tigerLineId": "76355984"
},
"coordinates": {
"x": -76.92744,
"y": 38.845985
},
"addressComponents": {
"zip": "20233",
"streetName": "SILVER HILL",
"preType": "",
"city": "WASHINGTON",
"preDirection": "",
"suffixDirection": "",
"fromAddress": "4600",
"state": "DC",
"suffixType": "RD",
"toAddress": "4700",
"suffixQualifier": "",
"preQualifier": ""
},
"matchedAddress": "4600 SILVER HILL RD, WASHINGTON, DC, 20233"
}]
}}

Examples using geoLookup:

https://geocoding.geo.census.gov/geocoder/geographies/address?street=4600+Silver+Hill+Rd&
city=Washington&state=DC&benchmark=Public_AR_Census2020&vintage=Census2020_Census2020&la
yers=10&format=json

Additional JSON response data for geoLookup:

"geographies": {"Census Blocks": [{

"SUFFIX": "",
"POP100": "",
"GEOID": "240338024052004",
"CENTLAT": "+38.8516945",
"BLOCK": "2004",
"AREAWATER": 2970,
"STATE": "24",
"BASENAME": "2004",
"OID": 210701008482815,
"LSADC": "BK",
"FUNCSTAT": "S",

4
 "INTPTLAT": "+38.8522266",
"NAME": "Block 2004",
"OBJECTID": 1679586,
"TRACT": "802405",
"CENTLON": "-076.9402961",
"BLKGRP": "2",
"AREALAND": 1745386,
"HU100": "",
"INTPTLON": "-076.9378719",
"MTFCC": "G5040",
"LWBLKTYP": "B",
"UR": "",
"COUNTY": "033"
}]}

Examples using geoLookup and benchmark Public_AR_Census2020 and vintage

Census2010_Census2020 to get 2010 blocks:

https://geocoding.geo.census.gov/geocoder/geographies/onelineaddress?address=4600+silver+
hill+rd%2C+20233&benchmark=2020&vintage=2010&format=json

https://geocoding.geo.census.gov/geocoder/geographies/onelineaddress?address=4600+silver+
hill+rd%2C+20233&benchmark=Public_AR_Census2020&vintage=Census2010_Census2020&format=jso
n

If a JSONP-formatted result is desired/required, the format=jsonp can be specified with a

corresponding Javascript callback method on the request.

Batch Geocoding
Geocoding can be accomplished in batch mode with submission of a .CSV, .TXT, .DAT, .XLS, or .XLSX
formatted file. The file needs to be included as part of the HTTP request.

The file must be formatted in the following way:

Unique ID, Street address, City, State, ZIP

If a component is missing from the dataset, it must still retain the delimited format with a null value.
Unique ID and Street address are required fields.

If there are commas that are part of one of the fields, the whole field needs to be enclosed in quote
marks for proper parsing.

There is currently an upper limit of 10,000 records per batch file.

The URL is as follows:

5
 https://geocoding.geo.census.gov/geocoder/returntype /addressbatch

Required Parameters
• returntype – locations (to get just geocoding response) or geographies (to get geocoding
response as well as geoLookup). Independent geoLookup (“coordinates” above) is not currently
an available batch option.
• benchmark – A numerical ID or name that references what version of the locator should be
searched. This generally corresponds to MTDB data which is benchmarked twice yearly. A full
list of options can be accessed at https://geocoding.geo.census.gov/geocoder/benchmarks. The
general format of the name is DatasetType_SpatialBenchmark. The valid values for these
include:
o DatasetType
▪ Public_AR
o SpatialBenchmark
▪ Current
▪ ACS2021
▪ Census2020
So a resulting benchmark name could be “Public_AR_Current”, “Public_AR_ACS2021”, etc. Over
time, there will always be a “Current” benchmark. It will change as the underlying dataset
changes.
• vintage – a numerical ID or name that references what vintage of geography is desired for
the geoLookup (only needed when returntype = geographies). A full list of options for a given
benchmark can be accessed at
https://geocoding.geo.census.gov/geocoder/vintages?benchmark=benchmarkId. The general
format of the name is GeographyVintage_SpatialBenchmark. The SpatialBenchmark variable
should always match the same named variable in what was chosen for the benchmark
parameter. The GeographyVintage can be Current, ACS2021, etc. So a resulting vintage name
could be “ACS2021_Current”, “Current_ ACS2021”, etc. Over time, there will always be a
“Current” vintage. It will change as the underlying dataset changes.
• addressFile – An input of type “file” containing the addresses to be coded

Example Shell Script Submission

curl --form [email protected] --form benchmark=2020
https://geocoding.geo.census.gov/geocoder/locations/addressbatch --output geocoderesult.csv