Geocoding Services
Web Application Programming Interface (API)
Last updated 08/2023
______________________________________________________________________________
Contents
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.
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.
A Geocoding Service API request must be in the following form:
https://geocoding.geo.census.gov/geocoder/returntype/searchtype?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
§ ACS2023
§ Census2020
So a resulting benchmark name could be “Public_AR_Current”, “Public_AR_ACS2023”, 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, ACS2023, etc. So a resulting vintage name could be “ACS2023_Current”, “Current_ACS2023”, 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.
· 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:
https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/tigerWMS_Current/MapServer
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/MapServer
Geocoding Services responses are returned in the format indicated by the format parameter value in the URL request’s path.
In this example, Geocoding Services API requests a json response for the address “4600 Silver Hill Rd, Washington, DC 20233”:
Other valid examples:
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"
}
},
"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"
}]
}}
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",
"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:
If a JSONP-formatted result is desired/required, the format=jsonp can be specified with a corresponding Javascript callback method on the request.
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:
https://geocoding.geo.census.gov/geocoder/returntype/addressbatch
· 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
§ ACS2023
§ Census2020
So a resulting benchmark name could be “Public_AR_Current”, “Public_AR_ACS2023”, 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, ACS2023, etc. So a resulting vintage name could be “ACS2023_Current”, “Current_ ACS2023”, 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
Locations Example:
curl --form addressFile=@localfile.csv --form benchmark=2020 https://geocoding.geo.census.gov/geocoder/locations/addressbatch
--output geocoderesult.csv
Geographies Example:
curl --form addressFile=@localfile.csv --form benchmark=2020 --form vintage=2020
https://geocoding.geo.census.gov/geocoder/geographies/addressbatch --output
geocoderesult.csv