| title | language_tabs | toc_footers | search | code_clipboard | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Geocodio API Reference |
|
|
true |
true |
Geocodio's RESTful API allows you to perform forward and reverse geocoding lookups. We support both batch requests as well as individual lookups.
You can also optionally ask for data appends such as timezone, Congressional districts or similar things of that nature.
The base API url is https://api.geocod.io/v1.7/.
All HTTP responses (including errors) are returned with JSON-formatted output.
We may add additional properties to the output in the future, but existing properties will never be changed or removed without a new API version release.
Note the versioning prefix in the base url, which is required for all requests.These libraries are officially written and maintained by Geocodio. Have an issue? We will in most cases be able to help via online chat or email.
GitHub pull requests and issues are also more than welcome!
| Platform | Library |
|---|---|
| PHP | Geocodio/geocodio-library-php |
| Node.js | Geocodio/geocodio-library-node |
| Ruby | Geocodio/geocodio-gem |
Thanks to the wonderful open-source community, we have language bindings for several additional languages and platforms.
We will do our best to assist in online chat or email, but may not be able to help in all cases with these libraries.
Some of the libraries are featured here with basic examples, but please make sure to check out the full documentation for the individual libraries (linked below).
| Platform | Library | Featured in documentation |
|---|---|---|
| Ruby | alexreisner/geocoder supports Geocodio thanks to PR by @dblockdotorg | |
| Ruby | davidcelis/geocodio by @davidcelis | |
| Python | bennylope/pygeocodio by @bennylope | |
| Clojure | jboverfelt/rodeo by @jboverfelt | |
| Perl | mrallen1/WebService-Geocodio by @bytemeorg | |
| Go | stevepartridge/geocodio by stevepartridge | |
| R | hrbrmstr/rgeocodio by hrbrmstr | |
| R | jessecambon/tidygeocoder by jessecambon | |
| C# | snake-plissken/cSharpGeocodio by Frank Deasey | |
| C# | arex388/Arex388.Geocodio by arex388 | |
| Rust | Cosiamo/geocodio_lib_rust by Cosiamo | |
| Java | deansg/jeocodio by Dean Gurvitz | |
| Are you the author of an awesome library that you would like to get featured here? Just let us know or create a pull request. | ||
Installing the library:
# Make sure to have `curl` installed to test the API in your terminal# Add the following to your Gemfile:
gem 'geocodio-gem'
# And then run:
bundle installpip install pygeocodio# Install via Composer
composer require geocodio/geocodio-library-php
<?php
require('vendor/autoload.php');
# Don't fancy Composer? Not a problem!
# Check out our sample code here: https://github.com/Geocodio/php-samples# Install via npm
$ npm install --save geocodio-library-node
# Install via Yarn
$ yarn add geocodio-library-node# Leiningen
[rodeo "2.0.1"]
# Maven
<dependency>
<groupId>rodeo</groupId>
<artifactId>rodeo</artifactId>
<version>2.0.1</version>
</dependency>
# Gradle
compile "rodeo:rodeo:2.0.1"To set the
API_KEY:
# With curl, you can just pass the query parameter with each request
curl "https://api.geocod.io/v1.7/api_endpoint_here?api_key=YOUR_API_KEY"require 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')from geocodio import GeocodioClient
client = GeocodioClient(YOUR_API_KEY)(ns my.ns
(:require [rodeo.core :refer :all]))
;; You can set the API key in the GEOCODIO_API_KEY environment variable
;; or with each request using the :api_key parameterAll requests require an API key. You can register here to get your own API key.
The API key must be included in all requests using the ?api_key=YOUR_API_KEY query parameter.
Accounts can have multiple API keys. This can be useful if you're working on several projects and want to be able to revoke access using the API key for a single project in the future or if you want to keep track of usage per API key.
You can also download a CSV of usage and fees per API key.
Make sure to replace YOUR_API_KEY with your personal API key found on the Geocodio dashboard.Geocoding (also known as forward geocoding) allows you to convert one or more addresses into geographic coordinates (i.e. latitude and longitude). Geocoding will also parse the address and append additional information (e.g. if you specify a zip code, Geocodio will return the city and state corresponding the zip code as well)
Geocodio supports geocoding of addresses, cities and zip codes in various formats.
Make sure to check the address formats section for more information on the different address formats supported.You can either geocode a single address at a time or collect multiple addresses in batches in order to geocode up to 10,000 addresses at the time.
Whenever possible, batch requests are recommended since they are significantly faster due to reduced network overhead.
A single address can be geocoded by making a simple GET request to the geocode endpoint, you can try this in your browser right now.
results are always ordered with the most accurate locations first. It is therefore always safe to pick the first result in the list.
To geocode a single address:
# Using q parameter
curl "https://api.geocod.io/v1.7/geocode?q=1109+N+Highland+St%2c+Arlington+VA&api_key=YOUR_API_KEY"
# Using individual address components
curl "https://api.geocod.io/v1.7/geocode?street=1109+N+Highland+St&city=Arlington&state=VA&api_key=YOUR_API_KEY"require 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
location = geocodio.geocode(['1109 N Highland St, Arlington VA'])from geocodio import GeocodioClient
client = GeocodioClient(YOUR_API_KEY)
location = client.geocode("1109 N Highland St, Arlington VA")<?php
$response = $geocoder->geocode('1109 N Highland St, Arlington VA');const Geocodio = require('geocodio-library-node');
const geocoder = new Geocodio('YOUR_API_KEY');
geocoder.geocode('1109 N Highland St, Arlington VA')
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
}
);(ns my.ns
(:require [rodeo.core :refer :all]))
(single "1109 N Highland St, Arlington VA" :api_key "YOUR_API_KEY")Example response:
{
"input": {
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201"
},
"results": [
{
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201",
"location": {
"lat": 38.886665,
"lng": -77.094733
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Virginia GIS Clearinghouse"
}
]
}GET https://api.geocod.io/v1.7/geocode
| Parameter | Description |
|---|---|
q |
The query (i.e. address) to geocode |
api_key |
Your Geocodio API key |
country |
Optional parameter. The country to geocode the address in. The default is to infer from the query, with a fallback to USA. |
fields |
Optional parameter to request additional field appends. |
limit |
Optional parameter. The maximum number of results to return. The default is no limit. If set to 0, no limit will be applied. |
format |
Optional parameter to change the JSON output format to a different pre-defined structure. Currently, "simple" is the only valid value. If not set, the default full JSON output structure is used. |
Alternative URL Parameters
Instead of using the q parameter, you can use a combination of street, city, state postal_code, and/or country. This can be useful if the address is already stored as separate fields on your end.
| Parameter | Description |
|---|---|
street |
E.g. 1600 Pennsylvania Ave NW |
city |
E.g. Washington |
state |
E.g. DC |
postal_code |
E.g. 20500 |
country |
E.g. Canada (Default to USA) |
# To receive a `simple` response, include the string `"simple"`
# as the fourth argument after any fields or limit parameters
# you have set.
require 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
response = geocodio.geocode(["1109 N Highland St, Arlington, VA"], [], nil, "simple")Example response when
formatis set tosimple:
{
"address": "1109 N Highland St, Arlington, VA 22201",
"lat": 38.886665,
"lng": -77.094733,
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Arlington"
}Example response when
formatis set tosimpleand no results are found:
{
"address": null,
"lat": null,
"lng": null,
"accuracy": null,
"accuracy_type": null,
"source": null
}In most cases, the standard output format would be used. In certain situations, it can however be beneficial to work with a JSON structure that is specifically designed for your use case.
simple format
When format is set to simple, a very simple JSON structure is outputted, with only basic information for the best matched results. This makes it much easier to work with the JSON document in situtations where extra verbosity is not needed.
The fields parameter is still supported when the simple output format is selected, but the limit parameter has no effect.
To geocode an address with a Unit Number
curl "https://api.geocod.io/v1.7/geocode?q=2800+Clarendon+Blvd+Suite+R500+Arlington+VA+22201&api_key=YOUR_API_KEY"Example response with Unit Number
{
"input": {
"address_components": {
"number": "2800",
"street": "Clarendon",
"suffix": "Blvd",
"secondaryunit": "Ste",
"secondarynumber": "R500",
"formatted_street": "Clarendon Blvd",
"city": "Arlington",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "2800 Clarendon Blvd, Ste R500, Arlington, VA 22201"
},
"results": [
{
"address_components": {
"number": "2800",
"street": "Clarendon",
"suffix": "Blvd",
"secondaryunit": "Ste",
"secondarynumber": "R500",
"formatted_street": "Clarendon Blvd",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "2800 Clarendon Blvd, Ste R500, Arlington, VA 22201",
"location": {
"lat": 38.887455,
"lng": -77.092018
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Arlington"
}
]
}If you include an Apartment or Suite number along as a suffix to the street name, we will parse that number and return it as part of your response. It will be broken out into the secondaryunit and secondarynumber keys within address_components.
For US addresses: The secondaryunit value will be standardized based on USPS records, if the unit number is deemed mailable and valid.
E.g. if the unit number is inputted as #R500, the outputted value will be Ste R500.
In order to verify that the unit number is valid per USPS, you can request the zip4 field append and check the exact_match value. If it is set to true it means that the unit number is accepted by USPS.
The input object that is returned in the API response is not a one-for-one parsing of the initial address that is provided. In order to ensure that the address_components returned in input are accurate, we cross-reference them with the address_components returned in the results object.
As such, if we aren't able to identify the exact address location in results, this could impact our ability to return a parsed address in input. In the vast majority of cases, the data returned will match the original address provided to the Geocodio API, but there may be some instances where we are not able to parse the exact input - especially in responses with lower accuracy_type values like place or street_center.
To perform batch geocoding:
curl -X POST \
-H "Content-Type: application/json" \
-d '["1109 N Highland St, Arlington VA", "525 University Ave, Toronto, ON, Canada", "4410 S Highway 17 92, Casselberry FL", "15000 NE 24th Street, Redmond WA", "17015 Walnut Grove Drive, Morgan Hill CA"]' \
https://api.geocod.io/v1.7/geocode?api_key=YOUR_API_KEYrequire 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
locations = geocodio.geocode(['1109 N Highland St, Arlington VA', '525 University Ave, Toronto, ON, Canada', '4410 S Highway 17 92, Casselberry FL', '15000 NE 24th Street, Redmond WA', '17015 Walnut Grove Drive, Morgan Hill CA'])from geocodio import GeocodioClient
client = GeocodioClient(YOUR_API_KEY)
locations = client.batch_geocode([
'1109 N Highland St, Arlington VA',
'525 University Ave, Toronto, ON, Canada',
'4410 S Highway 17 92, Casselberry FL',
'15000 NE 24th Street, Redmond WA',
'17015 Walnut Grove Drive, Morgan Hill CA'
])<?php
$addresses = [
'1109 N Highland St, Arlington VA',
'525 University Ave, Toronto, ON, Canada',
'4410 S Highway 17 92, Casselberry FL',
'15000 NE 24th Street, Redmond WA',
'17015 Walnut Grove Drive, Morgan Hill CA'
];
$response = $geocoder->geocode($addresses);const Geocodio = require('geocodio-library-node');
const geocoder = new Geocodio('YOUR_API_KEY');
const addresses = [
'1109 N Highland St, Arlington VA',
'525 University Ave, Toronto, ON, Canada',
'4410 S Highway 17 92, Casselberry FL',
'15000 NE 24th Street, Redmond WA',
'17015 Walnut Grove Drive, Morgan Hill CA'
];
geocoder.geocode(addresses)
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
}
);(ns my.ns
(:require [rodeo.core :refer :all]))
;; You can set the API key in the GEOCODIO_API_KEY environment variable
(batch ["1109 N Highland St, Arlington VA" "525 University Ave, Toronto, ON, Canada" "4410 S Highway 17 92, Casselberry FL" "15000 NE 24th Street, Redmond WA" "17015 Walnut Grove Drive, Morgan Hill CA"] :api_key "YOUR_API_KEY")Example response:
{
"results": [
{
"query": "1109 N Highland St, Arlington VA",
"response": {
"input": {
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"state": "VA",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA"
},
"results": [
{
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201",
"location": {
"lat": 38.886672,
"lng": -77.094735
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Arlington"
},
{
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201",
"location": {
"lat": 38.886665,
"lng": -77.094733
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Virginia Geographic Information Network (VGIN)"
}
]
}
},
{
"query": "525 University Ave, Toronto, ON, Canada",
"response": {
"input": {
"address_components": {
"number": "525",
"street": "University",
"suffix": "Ave",
"formatted_street": "University Ave",
"city": "Toronto",
"state": "ON",
"country": "CA"
},
"formatted_address": "525 University Ave, Toronto, ON"
},
"results": [
{
"address_components": {
"number": "525",
"street": "University",
"suffix": "Ave",
"formatted_street": "University Ave",
"city": "Toronto",
"state": "ON",
"country": "CA"
},
"formatted_address": "525 University Ave, Toronto, ON",
"location": {
"lat": 43.656258,
"lng": -79.388223
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "City of Toronto Open Data"
}
]
}
},
...
]
}If you have several addresses that you need to geocode, batch geocoding is a much faster option since it removes the overhead of having to perform multiple HTTP requests.
Batch geocoding requests are performed by making a POST request to the geocode endpoint, suppliying a JSON array or JSON object in the body with any key of your choosing.
POST https://api.geocod.io/v1.7/geocode
| Parameter | Description |
|---|---|
api_key |
Your Geocodio API key |
fields |
Optional parameter to request additional field appends. |
limit |
Optional parameter. The maximum number of results to return. The default is no limit. If set to 0, no limit will be applied. |
When making a batch geocoding request, you can POST queries as either a JSON array or a JSON object. If a JSON object is posted, you can specify a custom key for each element of your choice. This can be useful to match queries up with your existing data after the request is complete.
If using a JSON array, results are guaranteed to be returned in the same order as they are requested.
You can also use the alternative parameters with batch geocoding; just pass an associative array instead of a string for each address.
Here's a couple of examples of what the POST body can look like:
[
"1109 N Highland St, Arlington VA",
"525 University Ave, Toronto, ON, Canada",
"4410 S Highway 17 92, Casselberry FL",
"15000 NE 24th Street, Redmond WA",
"17015 Walnut Grove Drive, Morgan Hill CA"
]Example response when POST'ing JSON object:
{
"results": {
"FID1": {
"query": "1109 N Highland St, Arlington VA",
"response": {
"input": {
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"state": "VA",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA"
},
"results": [
{
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201",
"location": {
"lat": 38.886672,
"lng": -77.094735
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Arlington"
}
]
}
},
"FID2": {
...
},
"FID3": {
...
},
"FID4": {
...
},
"FID5": {
...
}
}
}{
"FID1": "1109 N Highland St, Arlington VA",
"FID2": "525 University Ave, Toronto, ON, Canada",
"FID3": "4410 S Highway 17 92, Casselberry FL",
"FID4": "15000 NE 24th Street, Redmond WA",
"FID5": "17015 Walnut Grove Drive, Morgan Hill CA"
}{
"1": {
"street": "1109 N Highland St",
"city": "Arlington",
"state": "VA"
},
"2": {
"city": "Toronto",
"country": "CA"
}
}When suppplying an address as individual components (instead of a single string) you can use a combination of street, city, state postal_code, and/or country. This can be useful if the address is already stored as separate fields on your end.
| Parameter | Description |
|---|---|
street |
E.g. 1600 Pennsylvania Ave NW |
city |
E.g. Washington |
state |
E.g. DC |
postal_code |
E.g. 20500 |
country |
E.g. Canada (Default to USA) |
Reverse geocoding is the process of converting latitude and longitude into a street address.
Geocodio will find matching street(s) and determine the correct house number based on the location. Note that Geocodio does not guarantee to return a valid house number; it is our closest approximation.
As with forward geocoding, you can either geocode a single set of coordinates at the time or collect multiple coordinates in batches. You can batch reverse geocode up to 10,000 coordinates at a time.
This endpoint can return up to 5 possible matches ranked and ordered by an accuracy score.
A geographic coordinate consists of latitude followed by longitude separated by a comma, for example38.9002898,-76.9990361
To reverse geocode a single coordinate:
curl "https://api.geocod.io/v1.7/reverse?q=38.9002898,-76.9990361&api_key=YOUR_API_KEY"require 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
addresses = geocodio.reverse(['38.9002898,-76.9990361'])from geocodio import GeocodioClient
client = GeocodioClient(YOUR_API_KEY)
addresses = client.reverse((38.9002898, -76.9990361))<?php
$response = $geocoder->reverse('38.9002898,-76.9990361');const Geocodio = require('geocodio-library-node');
const geocoder = new Geocodio('YOUR_API_KEY');
geocoder.reverse('38.9002898,-76.9990361')
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
}
);(ns my.ns
(:require [rodeo.core :refer :all]))
(single-reverse "38.9002898,-76.9990361" :api_key "YOUR_API_KEY")Example response:
{
"results": [
{
"address_components": {
"number": "508",
"street": "H",
"suffix": "St",
"postdirectional": "NE",
"formatted_street": "H St NE",
"city": "Washington",
"county": "District of Columbia",
"state": "DC",
"zip": "20002",
"country": "US"
},
"formatted_address": "508 H St NE, Washington, DC 20002",
"location": {
"lat": 38.900432,
"lng": -76.999031
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "City of Washington"
},
{
"address_components": {
"number": "510",
"street": "H",
"suffix": "St",
"postdirectional": "NE",
"formatted_street": "H St NE",
"city": "Washington",
"county": "District of Columbia",
"state": "DC",
"zip": "20002",
"country": "US"
},
"formatted_address": "510 H St NE, Washington, DC 20002",
"location": {
"lat": 38.900429,
"lng": -76.998965
},
"accuracy": 0.9,
"accuracy_type": "rooftop",
"source": "City of Washington"
},
...
]
}A single coordinate can be reverse geocoded by making a simple GET request to the reverse endpoint, you can try this in your browser right now.
GET https://api.geocod.io/v1.7/reverse
| Parameter | Description |
|---|---|
q |
The query (i.e. latitude/longitude pair) to geocode. The coordinate pair should be comma-separated |
api_key |
Your Geocodio API key |
fields |
Optional parameter to request additional field appends. |
limit |
Optional parameter. The maximum number of results to return. The default is no limit. If set to 0, no limit will be applied. |
format |
Optional parameter to change the JSON output format to a different pre-defined structure. Currently, "simple" is the only valid value. If not set, the default full JSON output structure is used. |
# To receive a `simple` response, include the string `"simple"`
# as the fourth argument after any fields or limit parameters
# you have set.
require 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
response = geocodio.reverse(["38.9002898,-76.9990361"], [], nil, "simple")Example response, when
formatis set tosimple:
{
"address": "508 H St NE, Washington, DC 20002",
"lat": 38.900432,
"lng": -76.999031,
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Statewide"
}Example response, when
formatis set tosimpleand no results are found:
{
"address": null,
"lat": null,
"lng": null,
"accuracy": null,
"accuracy_type": null,
"source": null
}In most cases, the standard output format would be used. In certain situations, it can however be beneficial to work with a JSON structure that is specifically designed for your use case.
simple format
When format is set to simple, a very simple JSON structure is outputted, with only basic information for the best matched results. This makes it much easier to work with the JSON document in situtations where extra verbosity is not needed.
The fields parameter is still supported when the simple output format is selected, but the limit parameter has no effect.
To perform batch reverse geocoding:
curl -X POST \
-H "Content-Type: application/json" \
-d '["35.9746000,-77.9658000","32.8793700,-96.6303900","33.8337100,-117.8362320","35.4171240,-80.6784760"]' \
https://api.geocod.io/v1.7/reverse?api_key=YOUR_API_KEYrequire 'geocodio/gem'
geocodio = Geocodio::Gem.new('YOUR_API_KEY')
address_sets = geocodio.reverse(['35.9746000,-77.9658000', '32.8793700,-96.6303900', '33.8337100,-117.8362320', '35.4171240,-80.6784760'])from geocodio import GeocodioClient
client = GeocodioClient(YOUR_API_KEY)
address_sets = client.reverse([
(35.9746000, -77.9658000),
(32.8793700, -96.6303900),
(33.8337100, -117.8362320),
(35.4171240, -80.6784760),
])<?php
$coordinates = [
'35.9746000,-77.9658000',
'32.8793700,-96.6303900',
'33.8337100,-117.8362320',
'35.4171240,-80.6784760'
];
$results = $geocoder->reverse($coordinates);const Geocodio = require('geocodio-library-node');
const geocoder = new Geocodio('YOUR_API_KEY');
const coordinates = [
'35.9746000,-77.9658000',
'32.8793700,96.6303900',
'33.8337100,117.8362320',
'35.4171240,-80.6784760'
];
geocoder.reverse(coordinates)
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
}
);(ns my.ns
(:require [rodeo.core :refer :all]))
(batch-reverse ["35.9746000,-77.9658000" "32.8793700,-96.6303900" "33.8337100,-117.8362320" "35.4171240,-80.6784760"] :api-key "YOUR_API_KEY")Example response (shortened for brevity):
{
"results": [
{
"query": "35.9746000,-77.9658000",
"response": {
"results": [
{
"address_components": {
"number": "101",
"predirectional": "W",
"street": "Washington",
"suffix": "St",
"formatted_street": "W Washington St",
"city": "Nashville",
"county": "Nash County",
"state": "NC",
"zip": "27856",
"country": "US"
},
"formatted_address": "101 W Washington St, Nashville, NC 27856",
"location": {
"lat": 35.974357,
"lng": -77.966064
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "NC Geographic Information Coordinating Council"
},
{
"address_components": {
"number": "100",
"predirectional": "E",
"street": "Washington",
"suffix": "St",
"formatted_street": "E Washington St",
"city": "Nashville",
"county": "Nash County",
"state": "NC",
"zip": "27856",
"country": "US"
},
"formatted_address": "100 E Washington St, Nashville, NC 27856",
"location": {
"lat": 35.974786,
"lng": -77.965387
},
"accuracy": 0.9,
"accuracy_type": "rooftop",
"source": "NC Geographic Information Coordinating Council"
},
...
]
}
},
{
"query": "32.8793700,-96.6303900",
"response": {
"results": [
{
"address_components": {
"number": "3034",
"predirectional": "S",
"street": "1st",
"suffix": "St",
"formatted_street": "S 1st St",
"city": "Garland",
"county": "Dallas County",
"state": "TX",
"zip": "75041",
"country": "US"
},
"formatted_address": "3034 S 1st St, Garland, TX 75041",
"location": {
"lat": 32.879386,
"lng": -96.630471
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "City of Garland"
},
...
]
}
},
...
]
}If you have several coordinates that you need to reverse geocode, batch reverse geocoding is a much faster option since it removes the overhead of having to perform multiple HTTP requests.
Batch reverse geocoding requests are performed by making a POST request to the reverse endpoint, suppliying a JSON array in the body.
POST https://api.geocod.io/v1.7/reverse
| Parameter | Description |
|---|---|
api_key |
Your Geocodio API key |
fields |
Optional parameter to request additional field appends. |
limit |
Optional parameter. The maximum number of results to return. The default is no limit. If set to 0, no limit will be applied. |
Example response:
{
"input": {
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"state": "VA",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA"
},
"results": [
{
"address_components": {
"number": "1109",
"predirectional": "N",
"street": "Highland",
"suffix": "St",
"formatted_street": "N Highland St",
"city": "Arlington",
"county": "Arlington County",
"state": "VA",
"zip": "22201",
"country": "US"
},
"formatted_address": "1109 N Highland St, Arlington, VA 22201",
"location": {
"lat": 38.886672,
"lng": -77.094735
},
"accuracy": 1,
"accuracy_type": "rooftop",
"source": "Arlington",
"fields": {
"congressional_districts": [
{
"name": "Congressional District 8",
"district_number": 8,
"ocd_id": "ocd-division/country:us/state:va/cd:8",
"congress_number": "118th",
"congress_years": "2023-2025",
"proportion": 1,
"current_legislators": [
{
"type": "representative",
"bio": {
"last_name": "Beyer",
"first_name": "Donald",
"birthday": "1950-06-20",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://beyer.house.gov",
"address": "1119 Longworth House Office Building Washington DC 20515-4608",
"phone": "202-225-4376",
"contact_form": null
},
"social": {
"rss_url": null,
"twitter": "RepDonBeyer",
"facebook": "RepDonBeyer",
"youtube": null,
"youtube_id": "UCPJGVbOVcAVGiBwq8qr_T9w"
},
"references": {
"bioguide_id": "B001292",
"thomas_id": "02272",
"opensecrets_id": "N00036018",
"lis_id": null,
"cspan_id": "21141",
"govtrack_id": "412657",
"votesmart_id": "1707",
"ballotpedia_id": "Don Beyer",
"washington_post_id": null,
"icpsr_id": "21554",
"wikipedia_id": "Don Beyer"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
},
{
"type": "senator",
"bio": {
"last_name": "Warner",
"first_name": "Mark",
"birthday": "1954-12-15",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://www.warner.senate.gov",
"address": "703 Hart Senate Office Building Washington DC 20510",
"phone": "202-224-2023",
"contact_form": "https://www.warner.senate.gov/public/index.cfm?p=Contact"
},
"social": {
"rss_url": "http://www.warner.senate.gov/public/?a=rss.feed",
"twitter": "MarkWarner",
"facebook": "MarkRWarner",
"youtube": "SenatorMarkWarner",
"youtube_id": "UCwyivNlEGf4sGd1oDLfY5jw"
},
"references": {
"bioguide_id": "W000805",
"thomas_id": "01897",
"opensecrets_id": "N00002097",
"lis_id": "S327",
"cspan_id": "7630",
"govtrack_id": "412321",
"votesmart_id": "535",
"ballotpedia_id": "Mark Warner",
"washington_post_id": null,
"icpsr_id": "40909",
"wikipedia_id": "Mark Warner"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
},
{
"type": "senator",
"bio": {
"last_name": "Kaine",
"first_name": "Timothy",
"birthday": "1958-02-26",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://www.kaine.senate.gov",
"address": "231 Russell Senate Office Building Washington DC 20510",
"phone": "202-224-4024",
"contact_form": "https://www.kaine.senate.gov/contact"
},
"social": {
"rss_url": "http://www.kaine.senate.gov/rss/feeds/?type=all",
"twitter": null,
"facebook": "SenatorKaine",
"youtube": "SenatorTimKaine",
"youtube_id": "UC27LgTZlUnBQoNEQFZdn9LA"
},
"references": {
"bioguide_id": "K000384",
"thomas_id": "02176",
"opensecrets_id": "N00033177",
"lis_id": "S362",
"cspan_id": "49219",
"govtrack_id": "412582",
"votesmart_id": "50772",
"ballotpedia_id": "Tim Kaine",
"washington_post_id": null,
"icpsr_id": "41305",
"wikipedia_id": "Tim Kaine"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
}
]
}
],
"state_legislative_districts": {
"house": [
{
"name": "State House District 47",
"district_number": "47",
"ocd_id": "ocd-division/country:us/state:va/sldl:47",
"is_upcoming_state_legislative_district": false,
"proportion": 1
}
],
"senate": [
{
"name": "State Senate District 31",
"district_number": "31",
"ocd_id": "ocd-division/country:us/state:va/sldu:31",
"is_upcoming_state_legislative_district": false,
"proportion": 1
}
]
}
}
}
]
}Geocodio allows you to request additional data with forward and reverse geocoding requests. We call this additional data fields.
To request additional data, just add a fields parameter to your query string and set the value according to the table below. You can request multiple data fields at the same time by separating them with a comma. If the fields parameter has been specified, a new fields key is exposed with each geocoding result containing all necessary data for each field.
Go ahead, try this in your browser right now.
Some fields are specific to the US and cannot be queried for other countries.
| Parameter name | Description | Coverage |
|---|---|---|
| cd, cd113, cd114, cd115, cd116, cd117, cd118, cd119 | Congressional District & Legislator information | US-only |
| stateleg, stateleg-next | State Legislative District (House & Senate) | US-only |
| school | School District (elementary/secondary or unified) | US-only |
| census, census2000, census2010, census2011, census2012, census2013, census2014, census2015, census2016, census2017, census2018, census2019, census2020, census2021, census2022, census2023 | Census Block/Tract, FIPS codes & MSA/CSA codes | US-only |
| acs-demographics | Demographics (Census) | US-only |
| acs-economics | Economics: Income Data (Census) | US-only |
| acs-families | Families (Census) | US-only |
| acs-housing | Housing (Census) | US-only |
| acs-social | Social: Education & Veteran Status (Census) | US-only |
| zip4 | USPS Zip+4 code and delivery information | US-only |
| riding, riding-next | Riding: Canadian Federal Electoral District | Canada-only |
| provriding, provriding-next | Riding: Canadian Provincial/Territorial Electoral District | Canada-only |
| statcan | Canadian statistical boundaries from Statistics Canada | Canada-only |
| timezone | Timezone |
Field name: cd, cd113, cd114, cd115, cd116, cd117, cd118, cd119
...
"fields": {
"congressional_districts": [
{
"name": "Congressional District 8",
"district_number": 8,
"ocd_id": "ocd-division/country:us/state:va/cd:8",
"congress_number": "118th",
"congress_years": "2023-2025",
"proportion": 1,
"current_legislators": [
{
"type": "representative",
"bio": {
"last_name": "Beyer",
"first_name": "Donald",
"birthday": "1950-06-20",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://beyer.house.gov",
"address": "1119 Longworth House Office Building Washington DC 20515-4608",
"phone": "202-225-4376",
"contact_form": null
},
"social": {
"rss_url": null,
"twitter": "RepDonBeyer",
"facebook": "RepDonBeyer",
"youtube": null,
"youtube_id": "UCPJGVbOVcAVGiBwq8qr_T9w"
},
"references": {
"bioguide_id": "B001292",
"thomas_id": "02272",
"opensecrets_id": "N00036018",
"lis_id": null,
"cspan_id": "21141",
"govtrack_id": "412657",
"votesmart_id": "1707",
"ballotpedia_id": "Don Beyer",
"washington_post_id": null,
"icpsr_id": "21554",
"wikipedia_id": "Don Beyer"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
},
{
"type": "senator",
"bio": {
"last_name": "Warner",
"first_name": "Mark",
"birthday": "1954-12-15",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://www.warner.senate.gov",
"address": "703 Hart Senate Office Building Washington DC 20510",
"phone": "202-224-2023",
"contact_form": "https://www.warner.senate.gov/public/index.cfm?p=Contact"
},
"social": {
"rss_url": "http://www.warner.senate.gov/public/?a=rss.feed",
"twitter": "MarkWarner",
"facebook": "MarkRWarner",
"youtube": "SenatorMarkWarner",
"youtube_id": "UCwyivNlEGf4sGd1oDLfY5jw"
},
"references": {
"bioguide_id": "W000805",
"thomas_id": "01897",
"opensecrets_id": "N00002097",
"lis_id": "S327",
"cspan_id": "7630",
"govtrack_id": "412321",
"votesmart_id": "535",
"ballotpedia_id": "Mark Warner",
"washington_post_id": null,
"icpsr_id": "40909",
"wikipedia_id": "Mark Warner"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
},
{
"type": "senator",
"bio": {
"last_name": "Kaine",
"first_name": "Timothy",
"birthday": "1958-02-26",
"gender": "M",
"party": "Democrat"
},
"contact": {
"url": "https://www.kaine.senate.gov",
"address": "231 Russell Senate Office Building Washington DC 20510",
"phone": "202-224-4024",
"contact_form": "https://www.kaine.senate.gov/contact"
},
"social": {
"rss_url": "http://www.kaine.senate.gov/rss/feeds/?type=all",
"twitter": null,
"facebook": "SenatorKaine",
"youtube": "SenatorTimKaine",
"youtube_id": "UC27LgTZlUnBQoNEQFZdn9LA"
},
"references": {
"bioguide_id": "K000384",
"thomas_id": "02176",
"opensecrets_id": "N00033177",
"lis_id": "S362",
"cspan_id": "49219",
"govtrack_id": "412582",
"votesmart_id": "50772",
"ballotpedia_id": "Tim Kaine",
"washington_post_id": null,
"icpsr_id": "41305",
"wikipedia_id": "Tim Kaine"
},
"source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"
}
]
}
],
},
...You can retrieve the Congressional district for an address or coordinate pair using any one of the valid parameter names in the fields query parameter. cd will always return the Congressional district for the current Congress while e.g. cd113 will continue to show the Congressional district for the 113th Congress.
The field returns the full name of the Congressional district, the district number, the Congress number, and the year range. If the current congress (i.e. cd or cd118) is specified, we will also return detailed information about the current legislators.
States with a single congressional district, will return a special "district_number" of 0 (i.e. Vermont).
Districts with non-voting delegates will return a special "district_number" of 98 (i.e. Washington DC).
Open Civic Data Division Identifiers (OCD-IDs) are returned for each district when using cd118.
When requesting boundaries for other congressional periods, the ocd_id property is still present, but set to null.
Geocodio can return the most likely Congressional districts given a ZIP code. In cases where there may be multiple possible Congressional districts for a postal code, we will return multiple Congressional districts, and rank them each using a proportion key. This key is a decimal percentage representation of how much of the district boundary that intersect with the zip code boundary (i.e. bigger number = more likely to be the correct district for citizens in that zip code).
Districts are always sorted by the proportion value in descending order (largest first).
Field name: stateleg or stateleg-next
Example lookup using a full address with
stateleg
...
"fields": {
"state_legislative_districts": {
"house": [
{
"name": "State House District 47",
"district_number": "47",
"ocd_id": "ocd-division/country:us/state:va/sldl:47",
"is_upcoming_state_legislative_district": false,
"proportion": 1
}
],
"senate": [
{
"name": "State Senate District 31",
"district_number": "31",
"ocd_id": "ocd-division/country:us/state:va/sldu:31",
"is_upcoming_state_legislative_district": false,
"proportion": 1
}
]
}
}
...You can retrieve the state legislative districts for an address or coordinate using stateleg in the fields query parameter. The stateleg-next can be used to retrieve state legislative districts based on upcoming district changes.
The field will return both the house and senate state legislative district (also known as lower and upper) with the full name and district number for each. For areas with a unicameral legislature (such as Washington, DC or Nebraska), the house and senate keys return the same district.
stateleg-next is a preview of upcoming redistricting changes for states that have off-year elections.
Where available, the state legislative district returned will be based on newly redistricted boundaries.
The following states are affected. Redistricted boundaries will be returned with the stateleg data append, after the noted cut-off date. Until then, stateleg-next is needed to retrieve districts based on redistricted boundaries.
- Washington: 8/6 2024
- Ohio: 1/1 2025
- New York Assembly districts: 1/1 2025
- Montana: 1/6 2025
- South Carolina (senate only): 1/7 2025
- Minnesota: 1/14 2025
- Kansas (senate only): 1/15 2025
- New Mexico (senate only): 1/21 2025
If new boundaries are not available, the current boundaries are used instead (effectively returning the same data as when the stateleg field append is used). The is_upcoming_state_legislative_district indicates whether redistricted data is returned.
Example lookup using a full address with
stateleg-next
...
"fields": {
"state_legislative_districts": {
"house": [
{
"name": "State House District 2",
"district_number": "2",
"ocd_id": "ocd-division/country:us/state:va/sldl:2",
"is_upcoming_state_legislative_district": true,
"proportion": 1
}
],
"senate": [
{
"name": "State Senate District 40",
"district_number": "40",
"ocd_id": "ocd-division/country:us/state:va/sldu:40",
"is_upcoming_state_legislative_district": true,
"proportion": 1
}
]
}
}
...Open Civic Data Division Identifiers (OCD-IDs) are returned for all legislative districts.
This id can be used as a unique identifier for each district.
Example lookup using the
22206zip code instead of a full address
...
"fields": {
"state_legislative_districts": {
"house": [
{
"name": "State House District 49",
"district_number": "49",
"ocd_id": "ocd-division/country:us/state:va/sldl:49",
"is_upcoming_state_legislative_district": false,
"proportion": 0.532
},
{
"name": "State House District 45",
"district_number": "45",
"ocd_id": "ocd-division/country:us/state:va/sldl:45",
"is_upcoming_state_legislative_district": false,
"proportion": 0.453
},
{
"name": "State House District 46",
"district_number": "46",
"ocd_id": "ocd-division/country:us/state:va/sldl:46",
"is_upcoming_state_legislative_district": false,
"proportion": 0.015
}
],
"senate": [
{
"name": "State Senate District 30",
"district_number": "30",
"ocd_id": "ocd-division/country:us/state:va/sldu:30",
"is_upcoming_state_legislative_district": false,
"proportion": 1
}
]
}
}
...Geocodio can return the most likely state legislative districts given a ZIP code. In cases where there may be multiple possible state legislative districts for a postal code, we will return multiple state legislative districts, and rank them each using a proportion key. This key is a decimal percentage representation of how much of the district boundary that intersect with the zip code boundary (i.e. bigger number = more likely to be the correct district for citizens in that zip code).
Districts are always sorted by the proportion in descending order (largest first).
Field name: school
Unified school district example
...
"fields": {
"school_districts": {
"unified": {
"name": "Desert Sands Unified School District",
"lea_code": "11110",
"grade_low": "KG",
"grade_high": "12"
}
},
}
...Elementary/Secondary school districts example
...
"fields": {
"school_districts": {
"elementary": {
"name": "Topsfield School District",
"lea_code": "11670",
"grade_low": "PK",
"grade_high": "06"
},
"secondary": {
"name": "Masconomet School District",
"lea_code": "07410",
"grade_low": "07",
"grade_high": "12"
}
}
}
}
...You can retrieve the school district for an address or coordinate using school in the fields query parameter.
The field will return either a unified school district or separate elementary and secondary fields depending on the area. Each school district is returned with its full name, the LEA (Local Education Agency) code, as well as the grades supported. Kindergarden is abbreviated as KG and pre-kindergarten is abbreviated as PK.
Field name: census, census2000, census2010, census2011, census2012, census2013, census2014, census2015, census2016, census2017, census2018, census2019, census2020, census2021, census2022, census2023
...
"fields": {
"census": {
"2010": {
"census_year": 2010,
"state_fips": "51",
"county_fips": "51013",
"tract_code": "101801",
"block_code": "1004",
"block_group": "1",
"full_fips": "510131018011004",
"place": {
"name": "Arlington",
"fips": "5103000"
},
"metro_micro_statistical_area": {
"name": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
"area_code": "47900",
"type": "metropolitan"
},
"combined_statistical_area": {
"name": "Washington-Baltimore-Northern Virginia, DC-MD-VA-WV",
"area_code": "51548"
},
"metropolitan_division": {
"name": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
"area_code": "47894"
},
"county_subdivision": {
"name": "Arlington",
"fips": "90072",
"fips_class": {
"class_code": "Z7",
"description": "A county subdivision that is coextensive with a county or equivalent feature or all or part of an incorporated place that the Census Bureau recognizes separately"
}
},
"source": "US Census Bureau"
},
"2023": {
"census_year": 2023,
"state_fips": "51",
"county_fips": "51013",
"tract_code": "101801",
"block_code": "2004",
"block_group": "2",
"full_fips": "510131018012004",
"place": {
"name": "Arlington",
"fips": "5103000"
},
"metro_micro_statistical_area": {
"name": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
"area_code": "47900",
"type": "metropolitan"
},
"combined_statistical_area": {
"name": "Washington-Baltimore-Arlington, DC-MD-VA-WV-PA",
"area_code": "548"
},
"metropolitan_division": {
"name": "Arlington-Alexandria-Reston, VA-WV",
"area_code": "11694"
},
"county_subdivision": {
"name": "Arlington",
"fips": "90072",
"fips_class": {
"class_code": "Z7",
"description": "A county subdivision that is coextensive with a county or equivalent feature or all or part of an incorporated place that the Census Bureau recognizes separately"
}
},
"source": "US Census Bureau"
}
}
}
...This will append various US Census-designated codes to your address.
Looking for Canadian Census data? See thestatcan field append.
You can request vintage data for every year back to the 2010 Census. This is done by specifying the year together with the field name, e.g. census2015 for 2015 data. It is also possible to request multiple years at the same time, e.g. census2010,census (as shown in the example response).
Data for the 2000 census is available as well, using the census2000 field append. Only County, Place, Tract and Block FIPS codes are returned for this Census year.
| Field | Description |
|---|---|
| census_year | The full year that the Census data belongs to (The U.S. Census Bureau might make slight boundary changes from year to year) |
| state_fips | The two-digit state FIPS code. A full list is available on Wikipedia |
| county_fips | The five-digit county FIPS code. The two first digits represents the state. A full list of US counties is available on Wikipedia |
| tract_code | The 6-digit census tract code. This is a subdivision of a county, used for statistical purposes. |
| block_code | The full 4-digit block code that the location belongs to. This is the smallest geographical unit that the U.S. Census Bureau provides statistical data for. |
| block_group | The single-digit group number for the block |
| full_fips | The full 15-digit fips code, consisting of the county fips, tract code and block code |
The U.S. Census Bureau also provides a more detailed guide for the above terms.
Using Census tracts and blocks, you can match addresses and latitude/longitude pairs with statistical data from the U.S. Census Bureau. For example, appending Census tracts and blocks to addresses enables you to utilize the American Community Survey (ACS) data.
This field is returned for locations that are within a census designated place. If the location is not in a census designated place, the API will return null instead of the individual fields.
You can read more about Census-designated places on Wikipedia.
| Field | Description |
|---|---|
| name | The official Census-designated name for the place |
| fips | The 7-digit place FIPS code. A place is defined as a city or other census designated area. A full list of ANSI codes is available from the U.S. Census Bureau |
This field is returned for locations that are within an MSA area. If no MSA area is associated with the location, the API will return null instead of the individual fields.
You can read more about Metropolitan and Micropolitan areas on Wikipedia.
| Field | Description |
|---|---|
| name | The official Census-designated name for the area |
| area_code | Unique code for the area, also known as the CBSA code |
| type | Can either be "metropolitan" or "micropolitan" |
This field is returned for locations that are within an CSA area. If no CSA area is associated with the location, the API will return null instead of the individual fields.
You can read more about Combined Statisical Areas on Wikipedia.
| Field | Description |
|---|---|
| name | The official Census-designated name for the area |
| area_code | Unique census-defined code for the area |
This field is returned for locations that are within a Metropolitan Division. If no area is associated with the location, the API will return null instead of the individual fields.
Metropolitan Divisions was introduced by the U.S. Census Bureau in 2003 to further split larger MSA's (Metropolitan Statistical Areas) into smaller groups.
You can read more about Metropolitan divisions on Wikipedia.
| Field | Description |
|---|---|
| name | The official Census-designated name for the area |
| area_code | Unique census-defined code for the area |
Depending on the state, this is either a MCD (Minor Civil Division) or CCD (Census County Division).
| Field | Description |
|---|---|
| name | The name of the county subdivision. Depending on the state, this could be a city/town/township name or a district number |
| fips | Unique census-defined code for the area |
| fips_class | The class_code and description for the given class code |
Geocodio can return results from the American Community Survey, for any given address in the US. This is performed by looking up 5-year estimates for the census block group associated with the address.
Please note that a single census block group can cover hundreds of households. As such, the returned data is not specific to the given location only.
We have divided ACS results into 5 categories: Demographics, Economics (Income Data), Families, Housing and Social (Education & Veteran Status).
For billing purposes, each category counts as an additional lookup. Do however note that the census field is always included with any acs- field lookups at no additional cost.
ACS field results are only returned for the following accuracy types:
rooftoprange_interpolationnearest_streetpointnearest_rooftop_matchstreet_center
As such, it is not possible to get ACS results for city or zip code results. Lookups are not counted towards account usage when ACS field appends are requested for these less accurate results.
ACS overall metadata:
...
"fields": {
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
}
...
}
}Individual ACS result metadata:
...
"Median age": {
"meta": {
"table_id": "B01002",
"universe": "Total population"
},
...
}A meta field with high level data information is returned for all acs results in general as well as individual ACS values.
This contains information about the exact ACS results we are using, including the years they are covering. We always use 5-year estimates, and always use the most recent data that is available.
When our ACS results are updated to a newer version, it is not considering a breaking change. This is done as soon as newer Census data is fully available and verified.
For each individual result, we return the official ACS table id as well as the "universe" that the values covers.
The universe can be values such as Households, Population 15 Years and Older, Total population, etc.
Field name: acs-demographics
...
"fields": {
"census": {...},
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
},
"demographics": {
"Median age": {
"meta": {
"table_id": "B01002",
"universe": "Total population"
},
"Total": {
"value": 29.8,
"margin_of_error": 2.9
},
"Male": {
"value": 29.8,
"margin_of_error": 2.1
},
"Female": {
"value": 29.9,
"margin_of_error": 4.3
}
},
"Population by age range": {
"meta": {
"table_id": "B01001",
"universe": "Total population"
},
"Total": {
"value": 1585,
"margin_of_error": 287
},
"Male": {
"value": 808,
"margin_of_error": 200,
"percentage": 0.51
},
"Male: Under 5 years": {
"value": 23,
"margin_of_error": 20,
"percentage": 0.028
},
"Male: 5 to 9 years": {
"value": 13,
"margin_of_error": 18,
"percentage": 0.016
},
"Male: 10 to 14 years": {
"value": 20,
"margin_of_error": 26,
"percentage": 0.025
},
"Male: 15 to 17 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 18 and 19 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 20 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 21 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 22 to 24 years": {
"value": 96,
"margin_of_error": 78,
"percentage": 0.119
},
"Male: 25 to 29 years": {
"value": 268,
"margin_of_error": 122,
"percentage": 0.332
},
"Male: 30 to 34 years": {
"value": 124,
"margin_of_error": 65,
"percentage": 0.153
},
"Male: 35 to 39 years": {
"value": 56,
"margin_of_error": 35,
"percentage": 0.069
},
"Male: 40 to 44 years": {
"value": 84,
"margin_of_error": 48,
"percentage": 0.104
},
"Male: 45 to 49 years": {
"value": 30,
"margin_of_error": 30,
"percentage": 0.037
},
"Male: 50 to 54 years": {
"value": 33,
"margin_of_error": 28,
"percentage": 0.041
},
"Male: 55 to 59 years": {
"value": 29,
"margin_of_error": 27,
"percentage": 0.036
},
"Male: 60 and 61 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 62 to 64 years": {
"value": 12,
"margin_of_error": 19,
"percentage": 0.015
},
"Male: 65 and 66 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 67 to 69 years": {
"value": 11,
"margin_of_error": 18,
"percentage": 0.014
},
"Male: 70 to 74 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 75 to 79 years": {
"value": 9,
"margin_of_error": 17,
"percentage": 0.011
},
"Male: 80 to 84 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 85 years and over": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female": {
"value": 777,
"margin_of_error": 139,
"percentage": 0.49
},
"Female: Under 5 years": {
"value": 30,
"margin_of_error": 27,
"percentage": 0.039
},
"Female: 5 to 9 years": {
"value": 7,
"margin_of_error": 11,
"percentage": 0.009
},
"Female: 10 to 14 years": {
"value": 21,
"margin_of_error": 24,
"percentage": 0.027
},
"Female: 15 to 17 years": {
"value": 25,
"margin_of_error": 33,
"percentage": 0.032
},
"Female: 18 and 19 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 20 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 21 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 22 to 24 years": {
"value": 113,
"margin_of_error": 106,
"percentage": 0.145
},
"Female: 25 to 29 years": {
"value": 195,
"margin_of_error": 63,
"percentage": 0.251
},
"Female: 30 to 34 years": {
"value": 119,
"margin_of_error": 52,
"percentage": 0.153
},
"Female: 35 to 39 years": {
"value": 63,
"margin_of_error": 48,
"percentage": 0.081
},
"Female: 40 to 44 years": {
"value": 44,
"margin_of_error": 30,
"percentage": 0.057
},
"Female: 45 to 49 years": {
"value": 54,
"margin_of_error": 39,
"percentage": 0.069
},
"Female: 50 to 54 years": {
"value": 24,
"margin_of_error": 21,
"percentage": 0.031
},
"Female: 55 to 59 years": {
"value": 7,
"margin_of_error": 13,
"percentage": 0.009
},
"Female: 60 and 61 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 62 to 64 years": {
"value": 30,
"margin_of_error": 31,
"percentage": 0.039
},
"Female: 65 and 66 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 67 to 69 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 70 to 74 years": {
"value": 14,
"margin_of_error": 21,
"percentage": 0.018
},
"Female: 75 to 79 years": {
"value": 31,
"margin_of_error": 37,
"percentage": 0.04
},
"Female: 80 to 84 years": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 85 years and over": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
}
},
"Sex": {
"meta": {
"table_id": "B01001",
"universe": "Total population"
},
"Total": {
"value": 1585,
"margin_of_error": 287
},
"Male": {
"value": 808,
"margin_of_error": 200,
"percentage": 0.51
},
"Female": {
"value": 777,
"margin_of_error": 139,
"percentage": 0.49
}
},
"Race and ethnicity": {
"meta": {
"table_id": "B03002",
"universe": "Total population"
},
"Total": {
"value": 1585,
"margin_of_error": 287
},
"Not Hispanic or Latino": {
"value": 1522,
"margin_of_error": 289,
"percentage": 0.96
},
"Not Hispanic or Latino: White alone": {
"value": 1175,
"margin_of_error": 257,
"percentage": 0.772
},
"Not Hispanic or Latino: Black or African American alone": {
"value": 36,
"margin_of_error": 31,
"percentage": 0.024
},
"Not Hispanic or Latino: American Indian and Alaska Native alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Not Hispanic or Latino: Asian alone": {
"value": 206,
"margin_of_error": 108,
"percentage": 0.135
},
"Not Hispanic or Latino: Native Hawaiian and Other Pacific Islander alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Not Hispanic or Latino: Some other race alone": {
"value": 23,
"margin_of_error": 25,
"percentage": 0.015
},
"Not Hispanic or Latino: Two or more races": {
"value": 82,
"margin_of_error": 62,
"percentage": 0.054
},
"Not Hispanic or Latino: Two or more races: Two races including Some other race": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Not Hispanic or Latino: Two or more races: Two races excluding Some other race, and three or more races": {
"value": 82,
"margin_of_error": 62,
"percentage": 1
},
"Hispanic or Latino": {
"value": 63,
"margin_of_error": 43,
"percentage": 0.04
},
"Hispanic or Latino: White alone": {
"value": 36,
"margin_of_error": 30,
"percentage": 0.571
},
"Hispanic or Latino: Black or African American alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Hispanic or Latino: American Indian and Alaska Native alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Hispanic or Latino: Asian alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Hispanic or Latino: Native Hawaiian and Other Pacific Islander alone": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Hispanic or Latino: Some other race alone": {
"value": 10,
"margin_of_error": 16,
"percentage": 0.159
},
"Hispanic or Latino: Two or more races": {
"value": 17,
"margin_of_error": 25,
"percentage": 0.27
},
"Hispanic or Latino: Two or more races: Two races including Some other race": {
"value": 17,
"margin_of_error": 25,
"percentage": 1
},
"Hispanic or Latino: Two or more races: Two races excluding Some other race, and three or more races": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
}
}
}
}
}
...We provide the data exactly as it is packaged by the Census Bureau in the breakouts it gives. The only change we have made is to add a "percentage" calculation to aid ease of use.
The data returned includes the following data points. For each data point, the data returned includes the value, margin of error, and percentage.
- Total (Table #B01002)
- total, male, female
- Population by age range (Table #B01001)
- Broken out by male and female
- under 5 years, 5-9 years, 10-14 years, 15-17 years, 18-19 years, 20 years, 21 years, 22-24 years, 25-29 years, 30-34 years, 35-39 years, 40-44 years, 45-49 years, 50-54 years, 55-59 years, 60-64 years, 65-69 years, 70-74 years, 75-79 years, 80-84 years, 85 years and over
- Sex (Table $B01001)
- total, male, female
- Race and ethnicity (Table #B03002)
- Broken out by not-Hispanic or Latino and Hispanic or Latino
- Not Hispanic or Latino, white alone, black or African American alone, American Indian and Alaska Native alone, Asian alone, Native Hawaiian and Other Pacific Islander alone; some other race alone; two or more races; two or more races: two races including some other race; two or more races: two races excluding some other race, and three or more races
Field name: acs-economics
...
"fields": {
"census": {...},
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
},
"economics": {
"Number of households": {
"meta": {
"table_id": "B19001",
"universe": "Households"
},
"Total": {
"value": 856,
"margin_of_error": 119
}
},
"Median household income": {
"meta": {
"table_id": "B19013",
"universe": "Households"
},
"Total": {
"value": 163646,
"margin_of_error": 9443
}
},
"Household income": {
"meta": {
"table_id": "B19001",
"universe": "Households"
},
"Less than $10,000": {
"value": 7,
"margin_of_error": 11,
"percentage": 0.008
},
"$10,000 to $14,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$15,000 to $19,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$20,000 to $24,999": {
"value": 23,
"margin_of_error": 34,
"percentage": 0.027
},
"$25,000 to $29,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$30,000 to $34,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$35,000 to $39,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$40,000 to $44,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$45,000 to $49,999": {
"value": 9,
"margin_of_error": 13,
"percentage": 0.011
},
"$50,000 to $59,999": {
"value": 8,
"margin_of_error": 13,
"percentage": 0.009
},
"$60,000 to $74,999": {
"value": 23,
"margin_of_error": 20,
"percentage": 0.027
},
"$75,000 to $99,999": {
"value": 93,
"margin_of_error": 55,
"percentage": 0.109
},
"$100,000 to $124,999": {
"value": 97,
"margin_of_error": 50,
"percentage": 0.113
},
"$125,000 to $149,999": {
"value": 101,
"margin_of_error": 53,
"percentage": 0.118
},
"$150,000 to $199,999": {
"value": 200,
"margin_of_error": 97,
"percentage": 0.234
},
"$200,000 or more": {
"value": 295,
"margin_of_error": 86,
"percentage": 0.345
}
}
}
}
}
...We provide the data exactly as it is packaged by the Census Bureau in the breakouts it gives. The only change we have made is to add a "percentage" calculation to aid ease of use.
The data returned includes the following data points. For each data point, the data returned includes the value, margin of error, and percentage.
- Median household income (Table #B19013)
- Household income (Table #B19001)
- less than $10,000; $10,000-$14,999; $15,000-$19,999; $20,000-$24,999; $25,000-$29,999; $30,000-$34,999; $40,000-$44,999; $45,000-$49,999; $50,000-$59,000; $60,000-$74,999; $75,000-$99,999; $100,000-$124,999; $125,000-$149,000; $150,000-$199,999; $200,000 or more
Field name: acs-families
...
"fields": {
"census": {...},
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
},
"families": {
"Household type by household": {
"meta": {
"table_id": "B11001",
"universe": "Households"
},
"Total": {
"value": 856,
"margin_of_error": 119
},
"Family households": {
"value": 272,
"margin_of_error": 70,
"percentage": 0.318
},
"Family households: Married-couple family": {
"value": 234,
"margin_of_error": 66,
"percentage": 0.86
},
"Family households: Other family": {
"value": 38,
"margin_of_error": 30,
"percentage": 0.14
},
"Family households: Other family: Male householder, no spouse present": {
"value": 6,
"margin_of_error": 9,
"percentage": 0.158
},
"Family households: Other family: Female householder, no spouse present": {
"value": 32,
"margin_of_error": 28,
"percentage": 0.842
},
"Nonfamily households": {
"value": 584,
"margin_of_error": 123,
"percentage": 0.682
},
"Nonfamily households: Householder living alone": {
"value": 320,
"margin_of_error": 91,
"percentage": 0.548
},
"Nonfamily households: Householder not living alone": {
"value": 264,
"margin_of_error": 114,
"percentage": 0.452
}
},
"Household type by population": {
"meta": {
"table_id": "B11002",
"universe": "Population in Households"
},
"Total": {
"value": 1585,
"margin_of_error": 287
},
"In family households": {
"value": 663,
"margin_of_error": 169,
"percentage": 0.418
},
"In family households: In married-couple family": {
"value": 550,
"margin_of_error": 159,
"percentage": 0.83
},
"In family households: In married-couple family: Relatives": {
"value": 550,
"margin_of_error": 159,
"percentage": 1
},
"In family households: In married-couple family: Nonrelatives": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"In family households: In male householder, no spouse present, family": {
"value": 16,
"margin_of_error": 27,
"percentage": 0.024
},
"In family households: In male householder, no spouse present, family: Relatives": {
"value": 11,
"margin_of_error": 18,
"percentage": 0.688
},
"In family households: In male householder, no spouse present, family: Nonrelatives": {
"value": 5,
"margin_of_error": 9,
"percentage": 0.313
},
"In family households: In female householder, no spouse present, family": {
"value": 97,
"margin_of_error": 83,
"percentage": 0.146
},
"In family households: In female householder, no spouse present, family: Relatives": {
"value": 90,
"margin_of_error": 76,
"percentage": 0.928
},
"In family households: In female householder, no spouse present, family: Nonrelatives": {
"value": 7,
"margin_of_error": 11,
"percentage": 0.072
},
"In nonfamily households": {
"value": 922,
"margin_of_error": 277,
"percentage": 0.582
}
},
"Marital status": {
"meta": {
"table_id": "B12001",
"universe": "Population 15 Years And Older"
},
"Male": {
"value": 752,
"margin_of_error": 196,
"percentage": 0.511
},
"Male: Never married": {
"value": 437,
"margin_of_error": 187,
"percentage": 0.581
},
"Male: Now married": {
"value": 308,
"margin_of_error": 71,
"percentage": 0.41
},
"Male: Now married: Married, spouse present": {
"value": 243,
"margin_of_error": 72,
"percentage": 0.789
},
"Male: Now married: Married, spouse absent": {
"value": 65,
"margin_of_error": 53,
"percentage": 0.211
},
"Male: Now married: Married, spouse absent: Separated": {
"value": 32,
"margin_of_error": 41,
"percentage": 0.492
},
"Male: Now married: Married, spouse absent: Other": {
"value": 33,
"margin_of_error": 30,
"percentage": 0.508
},
"Male: Widowed": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: Divorced": {
"value": 7,
"margin_of_error": 11,
"percentage": 0.009
},
"Female": {
"value": 719,
"margin_of_error": 139,
"percentage": 0.489
},
"Female: Never married": {
"value": 339,
"margin_of_error": 127,
"percentage": 0.471
},
"Female: Now married": {
"value": 229,
"margin_of_error": 66,
"percentage": 0.318
},
"Female: Now married: Married, spouse present": {
"value": 226,
"margin_of_error": 66,
"percentage": 0.987
},
"Female: Now married: Married, spouse absent": {
"value": 3,
"margin_of_error": 5,
"percentage": 0.013
},
"Female: Now married: Married, spouse absent: Separated": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: Now married: Married, spouse absent: Other": {
"value": 3,
"margin_of_error": 5,
"percentage": 1
},
"Female: Widowed": {
"value": 43,
"margin_of_error": 41,
"percentage": 0.06
},
"Female: Divorced": {
"value": 108,
"margin_of_error": 52,
"percentage": 0.15
}
}
}
}
}
...We provide the data exactly as it is packaged by the Census Bureau in the breakouts it gives. The only change we have made is to add a "percentage" calculation to aid ease of use.
The data returned includes the following data points. For each data point, the data returned includes the value, margin of error, and percentage.
- Family households (Table #B11001)
- total; married-couple family; other family; other family: male householder, no wife present; other family: female householder, no husband present; non-family households; non-family households -- householder living alone; non-family households -- householder not living alone
- Household type by population (Table #B11002)
- total; in family households; in married-couple family; in married-couple family: relatives; in married-couple family: non-relatives; in male householder, no wife present, family; in male householder, no wife present, family: relatives; in male householder, no wife present, family: nonrelatives; in female householder, no husband present, family; in female householder, no husband present, family: relatives; in female householder, no husband present, family: in nonfamily households
- Marital status (Table #B12001)
- never married; now married; now married: married, spouse present; married, spouse absent; married, spouse absent: separated; married, spouse absent: other; married, spouse absent, widowed; married, spouse absent, divorced; male never married; female never married
Field name: acs-housing
...
"fields": {
"census": {...},
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
},
"housing": {
"Number of housing units": {
"meta": {
"table_id": "B25002",
"universe": "Housing Units"
},
"Total": {
"value": 936,
"margin_of_error": 128
}
},
"Occupancy status": {
"meta": {
"table_id": "B25002",
"universe": "Housing Units"
},
"Occupied": {
"value": 856,
"margin_of_error": 119,
"percentage": 0.915
},
"Vacant": {
"value": 80,
"margin_of_error": 68,
"percentage": 0.085
}
},
"Ownership of occupied units": {
"meta": {
"table_id": "B25003",
"universe": "Occupied Housing Units"
},
"Owner occupied": {
"value": 212,
"margin_of_error": 67,
"percentage": 0.248
},
"Renter occupied": {
"value": 644,
"margin_of_error": 127,
"percentage": 0.752
}
},
"Units in structure": {
"meta": {
"table_id": "B25024",
"universe": "Housing Units"
},
"1, detached unit": {
"value": 5,
"margin_of_error": 10,
"percentage": 0.005
},
"1, attached unit": {
"value": 43,
"margin_of_error": 24,
"percentage": 0.046
},
"2 units": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"3 or 4 units": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"5 to 9 units": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"10 to 19 unit": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"20 to 49 units": {
"value": 34,
"margin_of_error": 28,
"percentage": 0.036
},
"50 or more units": {
"value": 854,
"margin_of_error": 124,
"percentage": 0.912
},
"Mobile home units": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Boat, RV, van, etc. units": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
}
},
"Median value of owner-occupied housing units": {
"meta": {
"table_id": "B25077",
"universe": "Owner-Occupied Housing Units"
},
"Total": {
"value": 665900,
"margin_of_error": 58612
}
},
"Value of owner-occupied housing units": {
"meta": {
"table_id": "B25075",
"universe": "Owner-Occupied Housing Units"
},
"Less than $10,000": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$10,000 to $14,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$15,000 to $19,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$20,000 to $24,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$25,000 to $29,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$30,000 to $34,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$35,000 to $39,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$40,000 to $49,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$50,000 to $59,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$60,000 to $69,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$70,000 to $79,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$80,000 to $89,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$90,000 to $99,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$100,000 to $124,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$125,000 to $149,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$150,000 to $174,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$175,000 to $199,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$200,000 to $249,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$250,000 to $299,999": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"$300,000 to $399,999": {
"value": 5,
"margin_of_error": 10,
"percentage": 0.024
},
"$400,000 to $499,999": {
"value": 28,
"margin_of_error": 28,
"percentage": 0.132
},
"$500,000 to $749,999": {
"value": 110,
"margin_of_error": 58,
"percentage": 0.519
},
"$750,000 to $999,999": {
"value": 12,
"margin_of_error": 14,
"percentage": 0.057
},
"$1,000,000 to $1,499,999": {
"value": 48,
"margin_of_error": 34,
"percentage": 0.226
},
"$1,500,000 to $1,999,999": {
"value": 9,
"margin_of_error": 13,
"percentage": 0.042
},
"$2,000,000 or more": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
}
}
}
}
}
...We provide the data exactly as it is packaged by the Census Bureau in the breakouts it gives. The only change we have made is to add a "percentage" calculation to aid ease of use.
For each data point, we return the value, margin of error, and percentage.
Data points returned are:
- Occupancy status (Table #B25002)
- occupied
- vacant
- Ownership of occupied units (Table #B25003)
- owner-occupied
- renter-occupied
- Units in structure (Table #B25024)
- 1, detached unit; 1, attached unit; 2 units; 3 or 4 units; 5 to 9 units; 10 to 19 units; 20 to 49 units; 50 or more units; mobile home units; boat, RV, van, etc. units
- Median value of owner-occupied housing units (Table #B25077)
- Value of owner-occupied housing units (Table # B25075)
- less than $10,000; $10,000-$14,999; $15,000-$19,999; $20,000-$29,000; $30,000-$34,999; $40,000-$49,999; $50,000-$59,000; $60,000-$69,999; $70,000-$79,000; $80,000-$89,999; $90,000-$99,999; $100,000-$124,999; $125,000-$149,000; $150,000-$174,999; $175,000-$199,999; $200,000-$249,000; $250,000-$299,000; $300,000-$399,999; $400,000-$499,000; $500,000-$749,000; $750,000-$999,999; $1,000,000-$1,499,999; $1,500,000-$1,999,999; $2,000,000 or more
Field name: acs-social
...
"fields": {
"census": {...},
"acs": {
"meta": {
"source": "American Community Survey from the US Census Bureau",
"survey_years": "2017-2021",
"survey_duration_years": "5"
},
"social": {
"Population by minimum level of education": {
"meta": {
"table_id": "B15002",
"universe": "Population 25 Years And Over"
},
"Total": {
"value": 1237,
"margin_of_error": 168
},
"Male": {
"value": 656,
"margin_of_error": 151,
"percentage": 0.53
},
"Male: No schooling completed": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: Nursery to 4th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 5th and 6th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 7th and 8th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 9th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 10th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 11th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 12th grade, no diploma": {
"value": 6,
"margin_of_error": 10,
"percentage": 0.009
},
"Male: High school graduate (includes equivalency)": {
"value": 6,
"margin_of_error": 9,
"percentage": 0.009
},
"Male: Some college, less than 1 year": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: Some college, 1 or more years, no degree": {
"value": 27,
"margin_of_error": 30,
"percentage": 0.041
},
"Male: Associate's degree": {
"value": 15,
"margin_of_error": 17,
"percentage": 0.023
},
"Male: Bachelor's degree": {
"value": 251,
"margin_of_error": 110,
"percentage": 0.383
},
"Male: Master's degree": {
"value": 216,
"margin_of_error": 99,
"percentage": 0.329
},
"Male: Professional school degree": {
"value": 118,
"margin_of_error": 55,
"percentage": 0.18
},
"Male: Doctorate degree": {
"value": 17,
"margin_of_error": 22,
"percentage": 0.026
},
"Female": {
"value": 581,
"margin_of_error": 99,
"percentage": 0.47
},
"Female: No schooling completed": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: Nursery to 4th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 5th and 6th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 7th and 8th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 9th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 10th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 11th grade": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 12th grade, no diploma": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: High school graduate (includes equivalency)": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: Some college, less than 1 year": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: Some college, 1 or more years, no degree": {
"value": 28,
"margin_of_error": 25,
"percentage": 0.048
},
"Female: Associate's degree": {
"value": 13,
"margin_of_error": 18,
"percentage": 0.022
},
"Female: Bachelor's degree": {
"value": 228,
"margin_of_error": 84,
"percentage": 0.392
},
"Female: Master's degree": {
"value": 207,
"margin_of_error": 70,
"percentage": 0.356
},
"Female: Professional school degree": {
"value": 80,
"margin_of_error": 40,
"percentage": 0.138
},
"Female: Doctorate degree": {
"value": 25,
"margin_of_error": 32,
"percentage": 0.043
}
},
"Population with veteran status": {
"meta": {
"table_id": "B21001",
"universe": "Civilian Population 18 Years And Over"
},
"Total": {
"value": 1412,
"margin_of_error": 286
},
"Veteran": {
"value": 57,
"margin_of_error": 39,
"percentage": 0.04
},
"Nonveteran": {
"value": 1355,
"margin_of_error": 286,
"percentage": 0.96
},
"Male": {
"value": 747,
"margin_of_error": 196,
"percentage": 0.529
},
"Male: Veteran": {
"value": 57,
"margin_of_error": 39,
"percentage": 0.076
},
"Male: Nonveteran": {
"value": 690,
"margin_of_error": 198,
"percentage": 0.924
},
"Male: 18 to 34 years": {
"value": 488,
"margin_of_error": 189,
"percentage": 0.653
},
"Male: 18 to 34 years: Veteran": {
"value": 13,
"margin_of_error": 21,
"percentage": 0.027
},
"Male: 18 to 34 years: Nonveteran": {
"value": 475,
"margin_of_error": 190,
"percentage": 0.973
},
"Male: 35 to 54 years": {
"value": 198,
"margin_of_error": 63,
"percentage": 0.265
},
"Male: 35 to 54 years: Veteran": {
"value": 33,
"margin_of_error": 28,
"percentage": 0.167
},
"Male: 35 to 54 years: Nonveteran": {
"value": 165,
"margin_of_error": 60,
"percentage": 0.833
},
"Male: 55 to 64 years": {
"value": 41,
"margin_of_error": 32,
"percentage": 0.055
},
"Male: 55 to 64 years: Veteran": {
"value": 11,
"margin_of_error": 16,
"percentage": 0.268
},
"Male: 55 to 64 years: Nonveteran": {
"value": 30,
"margin_of_error": 29,
"percentage": 0.732
},
"Male: 65 to 74 years": {
"value": 11,
"margin_of_error": 18,
"percentage": 0.015
},
"Male: 65 to 74 years: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 65 to 74 years: Nonveteran": {
"value": 11,
"margin_of_error": 18,
"percentage": 1
},
"Male: 75 years and over": {
"value": 9,
"margin_of_error": 17,
"percentage": 0.012
},
"Male: 75 years and over: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Male: 75 years and over: Nonveteran": {
"value": 9,
"margin_of_error": 17,
"percentage": 1
},
"Female": {
"value": 665,
"margin_of_error": 130,
"percentage": 0.471
},
"Female: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: Nonveteran": {
"value": 665,
"margin_of_error": 130,
"percentage": 1
},
"Female: 18 to 34 years": {
"value": 427,
"margin_of_error": 126,
"percentage": 0.642
},
"Female: 18 to 34 years: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 18 to 34 years: Nonveteran": {
"value": 427,
"margin_of_error": 126,
"percentage": 1
},
"Female: 35 to 54 years": {
"value": 156,
"margin_of_error": 60,
"percentage": 0.235
},
"Female: 35 to 54 years: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 35 to 54 years: Nonveteran": {
"value": 156,
"margin_of_error": 60,
"percentage": 1
},
"Female: 55 to 64 years": {
"value": 37,
"margin_of_error": 32,
"percentage": 0.056
},
"Female: 55 to 64 years: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 55 to 64 years: Nonveteran": {
"value": 37,
"margin_of_error": 32,
"percentage": 1
},
"Female: 65 to 74 years": {
"value": 14,
"margin_of_error": 21,
"percentage": 0.021
},
"Female: 65 to 74 years: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 65 to 74 years: Nonveteran": {
"value": 14,
"margin_of_error": 21,
"percentage": 1
},
"Female: 75 years and over": {
"value": 31,
"margin_of_error": 37,
"percentage": 0.047
},
"Female: 75 years and over: Veteran": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Female: 75 years and over: Nonveteran": {
"value": 31,
"margin_of_error": 37,
"percentage": 1
}
},
"Period of military service for veterans": {
"meta": {
"table_id": "B21002",
"universe": "Civilian Veterans 18 Years And Over"
},
"Total": {
"value": 57,
"margin_of_error": 39
},
"Gulf War (9/2001 or later), no Gulf War (8/1990 to 8/2001), no Vietnam Era": {
"value": 34,
"margin_of_error": 34,
"percentage": 0.596
},
"Gulf War (9/2001 or later) and Gulf War (8/1990 to 8/2001), no Vietnam Era": {
"value": 18,
"margin_of_error": 20,
"percentage": 0.316
},
"Gulf War (9/2001 or later), and Gulf War (8/1990 to 8/2001), and Vietnam Era": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Gulf War (8/1990 to 8/2001), no Vietnam Era": {
"value": 3,
"margin_of_error": 6,
"percentage": 0.053
},
"Gulf War (8/1990 to 8/2001) and Vietnam Era": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Vietnam Era, no Korean War, no World War II": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Vietnam Era and Korean War, no World War II": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Vietnam Era and Korean War and World War II": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Korean War, no Vietnam Era, no World War II": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Korean War and World War II, no Vietnam Era": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"World War II, no Korean War, no Vietnam Era": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Between Gulf War and Vietnam Era only": {
"value": 2,
"margin_of_error": 8,
"percentage": 0.035
},
"Between Vietnam Era and Korean War only": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Between Korean War and World War II only": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
},
"Pre-World War II only": {
"value": 0,
"margin_of_error": 13,
"percentage": 0
}
}
}
}
}
...We provide the data exactly as it is packaged by the Census Bureau in the breakouts it gives. The only change we have made is to add a "percentage" calculation to aid ease of use.
The data returned includes the following data points. For each data point, the data returned includes the value, margin of error, and percentage.
- Population by minimum level of education (Table #B15002)
- No schooling, nursery to 4th grade, 5th and 6th grade, 7th and 8th grade, 9th grade, 10th grade, 11th grade, 12th grade - no diploma, high school graduate or equivalent, some college (1+ years, no degree), Associate's Degree, Bachelor's Degree, Master's Degree, professional school degree, Doctorate
- Results broken out by all genders, female, and male
- Veteran status (Table #B21001)
- Veteran, non-Veteran
- Results broken out by all genders, female, and male as well as age groups
- Period of military service for veterans (Table #B21002)
- Wars
- Gulf War (9/2001 or later), no Gulf War (8/1990 to 8/2001), no Vietnam Era
- Gulf War (9/2001 or later), Gulf War (8/1990 to 8/2001), no Vietnam Era
- Gulf War (8/1990 to 8/2001), no Vietnam Era
- Gulf War (8/1990 to 8/2001) and Vietnam Era
- Vietnam Era, no Korean War, no World War II
- Vietnam Era and Korean War, no World War II
- Vietnam Era and Korean War and World War II
- Korean War, no Vietnam Era, no World War II
- Korean War and World War II, no Vietnam Era
- World War II, no Korean War, no Vietnam Era
- Between Gulf War and Vietnam Era only
- Between Korean War and World War II only
- Pre-World War II only
- Wars
Field name: zip4
...
"fields": {
"zip4": {
"record_type": {
"code": "S",
"description": "Street"
},
"residential": false,
"carrier_route": {
"id": "C007",
"description": "City Delivery"
},
"building_or_firm_name": null,
"plus4": [
"2890"
],
"zip9": [
"22201-2890"
],
"government_building": null,
"facility_code": {
"code": "P",
"description": "Post Office"
},
"city_delivery": true,
"valid_delivery_area": true,
"exact_match": true
}
}
...zip4 data append requires using v1.5 of the Geocodio API or newer.
In most cases, only a single ZIP4 code is assigned to a result. If that is the case each array has one item.
...
"plus4": [
"2890"
],
"zip9": [
"22201-2890"
],
...For businesses with a range of ZIP4 codes, an array with 2 items is returned:
...
"plus4": [
"2890",
"2900",
],
"zip9": [
"22201-2890",
"22201-2900"
],
...In some rare cases a ZIP4 record is returned but without a ZIP+4 code (e.g. when it is not a valid delivery area)
...
"plus4": [],
"zip9": [],
...Example of a building or firm name being returned (316 Pennsylvania Ave. SE, Lobby, Washington, DC)
...
"building_or_firm_name": "The Natl Capital Bank Of Washington",
...Example of a government building result (134 Union Blvd Ste 130 Lakewood, CO)
...
"government_building": {
"code": "B",
"description": "Federal Government Building"
},
...This performs a lookup to determine the USPS ZIP+4 code for a given US location, this lets you retrieve the full 9-digit ZIP Code™, by combining the 5-digit ZIP code with the ZIP+4 code.
Additional USPS delivery data is also returned.
The type of ZIP+4 result. Possible values are:
- F: Firm
- G: General Delivery
- H: High-rise
- P: PO Box
- R: Rural Route/Contract
- S: Street
residential will be set to true for residential addreses and false for commercial addresses.
The value can also be null if there are no records that indicate the residential status of this property.
A 4-byte code that determines the type of postal route that that servers the address. Possible values are:
- Bxxx: PO Box
- Hxxx: Contract
- Rxxx: Rural Route
- Cxxx: City Delivery
- Gxxx: General Delivery
A USPS-provided name associated with the address. This is available for businesses that have registered their name with USPS and for most federal and state government buildings including schools and offices.
The building or firm name field takes the secondary address unit into account if available.
If no name is available, the value is set to null.
The range of ZIP Codes that are associated with this result as representated by the minimum and maximum number.
The ZIP9 code consists of the ZIP5 code, a dash, and the +4 code.
Type of government building (if applicable).
If no name is available, the value is set to null.
- A: City Government Building
- B: Federal Government Building
- C: State Government Building
- D: Firm Only
- E: City Government Building and Firm Only
- F: Federal Government Building
- G: State Government Building and Firm Only
Facility code associated with the 5-digit ZIP Code
Possible values are:
- B: Branch
- C: Community post office (CPO)
- N: Non-postal community name, former USPS facility, or place name
- P: Post Office
- S: Station
- U: Urbanization
Indicates whether our not the local post office has a city delivery carrier route.
In some cases an address exists but it is not a valid delivery point for postal purposes. This could for example be because it is an undeveloped lot.
An exact match means that there was no ambiguity with the lookup and that the given ZIP+4 code is the correct and only match for the given address.
Most often, not-exact matches are due to lookups for an apartment or office building that is missing a unit/apartment number.
In these cases it is not possible to determine an accurate ZIP+4 code without supplying secondary address line information.
If no ZIP+4 data is available for the given query, the `zip4` field is omitted from the JSON output (and the field lookup does not count against your usage)Field name: riding or riding-next
Example for "300 King St, Sturgeon Falls, ON P2B 3A1, Canada"
...
"fields": {
"riding": {
"year": 2013,
"code": "35070",
"ocd_id": "ocd-division/country:ca/ed:35070-2013",
"name_french": "Nipissing--Timiskaming",
"name_english": "Nipissing--Timiskaming",
"source": "Statistics Canada"
}
}
...Look up the riding for the specified address in Canada. The riding code and OCD-ID is returned along with the French and English name for the riding.
The OCD-ID can be used to uniquely identify the district, using the Open Civic Data Division Identifiers project.
In some cases the French and English names will be the same.
riding-next is a preview of upcoming, redistricted ridings. The redistricted ridings were established in 2023 and will be in effect for a federal general election called any time after April 22, 2024.
Example for "300 King St, Sturgeon Falls, ON P2B 3A1, Canada"
...
"fields": {
"riding": {
"year": 2023,
"code": "35073",
"ocd_id": "ocd-division/country:ca/ed:35073-2023",
"name_french": "Nipissing—Timiskaming",
"name_english": "Nipissing—Timiskaming",
"source": "Federal Redistribution"
}
}
...Field name: provriding or provriding-next
Example for "300 King St, Sturgeon Falls, ON P2B 3A1, Canada"
...
"fields": {
"provincial_riding": {
"ocd_id": "ocd-division/country:ca/province:on/ed:72-2015",
"name_french": "Nipissing",
"name_english": "Nipissing",
"is_upcoming_district": false,
"source": "Elections Ontario"
}
}
...Look up the provincial or territorial electoral district for the specified address in Canada. The OCD-ID is returned along with the French and English name for the riding.
The OCD-ID can be used to uniquely identify the district, using the Open Civic Data Division Identifiers project.
In some cases the French and English names will be the same.
provriding-next is a preview of upcoming, redistricted provincial ridings.
Example for "203 Laycoe Crescent, Saskatoon, SK, Canada"
...
"fields": {
"provincial_riding": {
"ocd_id": "ocd-division/country:ca/province:sk/ed:52-2022",
"name_french": "Saskatoon University-Sutherland",
"name_english": "Saskatoon University-Sutherland",
"is_upcoming_district": true,
"source": "Elections Saskatchewan"
}
}
...Field name: statcan
Example for "300 King St, Sturgeon Falls, ON P2B 3A1, Canada"
...
"fields": {
"statcan": {
"division": {
"id": "3549",
"name": "Parry Sound",
"type": "DIS",
"type_description": "District"
},
"consolidated_subdivision": {
"id": "3549066",
"name": "Callander"
},
"subdivision": {
"id": "3549066",
"name": "Callander",
"type": "MU",
"type_description": "Municipality"
},
"economic_region": "Northeast / Nord-est",
"statistical_area": {
"code": "575",
"code_description": "CMA or CA",
"type": "2",
"type_description": "Census subdivision within census agglomeration with at least one census tract"
},
"cma_ca": {
"id": "575",
"name": "North Bay",
"type": "K",
"type_description": "Census agglomeration (CA) that is tracted"
},
"tract": "5750100.00",
"designated_place": null,
"population_centre": {
"id": "350595",
"name": "North Bay",
"type": "1",
"type_description": "Core inside of a census metropolitan area or census agglomeration",
"class": "3",
"class_description": "Medium population centre (30,000 to 99,999)"
},
"dissemination_area": {
"id": "35490146"
},
"dissemination_block": {
"id": "35490146015",
"population": "155"
},
"census_year": 2021
}
}
...Retrieve the Statistics Canada boundaries that the given query is within. These boundaries can be matched with data from Statistics Canada to get demographic information about the area the query is within.
Looking for US Census data? See thecensus field append.
If a given geography does not apply to the query, null will be returned instead.
Example for "26 Johnson Avenue, Teslin, YT Y0A 1B0, Canada"
...
"fields": {
"statcan": {
"division": {
"id": "6001",
"name": "Yukon",
"type": "TER",
"type_description": "Territory / Territoire"
},
"consolidated_subdivision": {
"id": "6001045",
"name": "Yukon, Unorganized"
},
"subdivision": {
"id": "6001047",
"name": "Johnsons Crossing",
"type": "SÉ",
"type_description": "Not applicable"
},
"economic_region": "Yukon",
"statistical_area": {
"code": "000",
"code_description": "Territories, classification is not applicable",
"type": "8",
"type_description": "Census subdivision within a territory"
},
"cma_ca": null,
"tract": null,
"designated_place": null,
"population_centre": {
"id": "609960",
"name": "Yukon Territory Rural Area / Région rurale: Territoire du Yukon",
"type": "5",
"type_description": "Rural area outside of a census metropolitan area or census agglomeration",
"class": "1",
"class_description": "Rural area"
},
"dissemination_area": {
"id": "60010135"
},
"dissemination_block": {
"id": "60010135008",
"population": "10"
},
"census_year": 2021
}
}
...The following geographies may be found:
One of the largest Census designated geographies. The id, name and type code for the query is returned. The type_description contains values such as "District", "County", "Region", among others.
A geographic unit that is in-between divisions and subdivisions in size. It is a combination of adjacent census subdivisions.
The id and name are returned for consolidated subdivisions
This generally corresponds to a municipality.
The subdivision id is returned along with it's name and type code. The type_description is an explanation of the type code and can contain values such as "Town", "Village", "Municipality" or "City" among many others.
Economic regions are mostly groupings of complete census divisions, created to allow for analysis of regional economic activity.
Statistical areas group census subdivisions based on what type of CMA/CA are they are part of.
The Census Metropolitan Area or Census Agglomeration that the query is part of. type_description can be either of the following: "Census metropolitan area (CMA)", "Census agglomeration (CA) that is not tracted", "Census agglomeration (CA) that is tracted".
The full Canadian census tract code that this query is part of.
A Designated Place (DPL) typically refers to a small community or settlement that doesn't fulfill Statistics Canada's requirements for being a census subdivision (an area with municipal status) or a population centre.
Provinces and territories work with Statistics Canada to establish designated places, which serve as data sources for submunicipal regions.
Population centres in Canada have a population of at least 1,000 and a population density of 400 persons or more per square kilometre, based on the current census population count. Rural areas are defined as areas outside population centres. All of Canada is covered by either population centres or rural areas.
Population centres are grouped into three categories based on their population size: small, medium, and large. The population count for population centres includes all people living in the cores, secondary cores, and fringes of census metropolitan areas and census agglomerations, as well as those living in population centres outside of these areas.
The dissemination area is geographically one step lower than census tracts. Dissemination blocks are one step lower than dissemination areas.
You can read more about the various code names from the Statistics Canada technical specifications page. Statistics Canada also provides a helpful hierarchy of geographic areas.
Field name: timezone
...
"fields": {
"timezone": {
"name": "America/New_York",
"utc_offset": -5,
"observes_dst": true,
"abbreviation": "EST",
"source": "© OpenStreetMap contributors"
}
}
...You can retrieve the timezone for an address or coordinate using timezone in the fields query parameter.
The field will return the standardized name of the timezone as well as an abbreviation (see table below for examples), the UTC/GMT offset, and whether the location observes Daylight Saving Time (DST).
The standardized name follows the tzdb format. E.g. America/New_York.
| Abbreviation | Description |
|---|---|
| AKST | Alaska Standard Time |
| AST | Atlantic Standard Time |
| ChST | Chamorro Standard Time |
| CST | Central Standard Time |
| EST | Eastern Standard Time |
| HAST | Hawaii-Aleutian Standard Time |
| MST | Mountain Standard Time |
| PST | Pacific Standard Time |
| SST | Samoa Standard Time |
All results come with an address_components dictionary. This is an overview of all of the possible keys that you may find.
The key will not be present if there is no valid value for it. E.g. if the address does not have a predirectional, this key will not be present.
| Name | Notes |
|---|---|
| number | House number, e.g. "2100" or "250 1/2" |
| predirectional | Directional that comes before the street name, 1-2 characters, e.g. N or NE |
| prefix | Abbreviated street prefix, particularily common in the case of French addresse e.g. Rue, Boulevard, Impasse |
| street | Name of the street without number, prefix or suffix, e.g. "Main" |
| suffix | Abbreviated street suffix, e.g. St., Ave. Rd. |
| postdirectional | Directional that comes after the street name, 1-2 characters, e.g. N or NE |
| secondaryunit | Name of the secondary unit, e.g. "Apt" or "Unit". For "input" address components only |
| secondarynumber | Secondary unit number. For "input" address components only |
| city | |
| county | |
| state | |
| zip | 5-digit zip code for US addresses. The 3-character FSA is returned for Canadian results - the full postal code is not returned |
| country | |
| formatted_street | Fully formatted street, including all directionals, suffix/prefix but not house number |
Each geocoded result is returned with an accuracy score, which is a decimal number ranging from 0.00 to 1.00. This score is generated by the internal Geocodio engine based on how accurate the result is believed to be. The higher the score, the better the result. Results are always returned ordered by accuracy score.
For example, if against all odds an address simply can't be found, instead of returning no results, Geocodio will return a geocoded point based on the postal code or city but with a much lower accuracy score and accuracy type set to "place".
Generally, accuracy scores that are larger than or equal to 0.8 are the most accurate, whereas results with lower accuracy scores might be very rough matches.
An accuracy type is also returned with all results. The accuracy types are different for forward and reverse geocoding results.
We recommend using a combination of the accuracy score and accuracy type to evaluate and filter the returned results.
| Value | Description |
|---|---|
| rooftop | The exact point was found with rooftop level accuracy |
| point | The exact point was found from address range interpolation where the range contained a single point |
| range_interpolation | The point was found by performing address range interpolation |
| nearest_rooftop_match | The exact house number was not found, so a close, neighboring house number was used instead |
| intersection | The result is an intersection between two streets |
| street_center | The result is a geocoded street centroid |
| place | The point is a city/town/place zip code centroid |
| county | The point is a county centroid |
| state | The point is a state centroid |
Visual guide to the most common accuracy types
| Value | Description |
|---|---|
| rooftop | We found the exact point with rooftop level accuracy |
| nearest_street | Nearest match for a specific street with estimated street number |
| nearest_place | Closest city/town/place |
Geocodio supports geocoding the following address components:
- Streets with or without house numbers (requires a city or a zip in conjuction)
- Intersections
- Cities
- Zip codes
- Counties
- States
- PO Boxes (coordinates will be returned as a centroid of the zip code)
- Second address lines such as unit and apartment numbers (not used for determining the exact coordinates at this time)
If a city is provided without a state, Geocodio will automatically guess and add the state based on what it is most likely to be. Geocodio also understands shorthands for both streets and cities, for example NYC, SF, etc., are acceptable city names.
Geocoding queries can be formatted in various ways:
- 1109 N Highland St, Arlington VA
- 1109 N Highland Street, Arlington VA
- 1109 North Highland Street, Arlington VA
- 1109 N Highland St, Arlington VA
- 1109 N Highland St, 22201
- Arlington, VA
- Arlington
- VA
- 22201
- PO Box 4735, Tulsa OK
- Santa Clara County
- Santa Clara County, CA
- 1 Infinite Loop, Santa Clara County
- 1 Infinite Loop, Santa Clara County, CA
- 1 Infinite Loop, Santa Clara County, Cupertino CA
If a country is not specified in the query, the Geocodio engine will assume the country to be USA.
Examples of Canadian lookups:
You can also geocode intersections. Just specify the two streets that you want to geocode in your query. We support various formats:
- E 58th St and Madison Ave, New York, NY
- Market and 4th, San Francisco
- Commonwealth Ave at Washington Street, Boston, MA
- Florencia & Perlita, Austin TX
- Quail Trail @ Dinkle Rd, Edgewood, NM
- 8th St SE/I St SE, 20003
An extra address_components_secondary property will be exposed for intersection results, but otherwise, the schema format is the same.
{
...
"results": [
{
"address_components": {
"street": "4th",
"suffix": "St",
"formatted_street": "4th St",
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"zip": "94103"
},
"address_components_secondary": {
"street": "Market",
"suffix": "St",
"formatted_street": "Market St",
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"zip": "94103"
},
"formatted_address": "4th St and Market St, San Francisco, CA 94103",
"location": {
"lat": 37.785725,
"lng": -122.405807
},
"accuracy": 1,
"accuracy_type": "intersection",
"source": "TIGER/Line® dataset from the US Census Bureau"
}
]
...
}Here is an example of a 422 Unprocessable Entity response:
{
"error": "Could not geocode address, zip code or city/state are required"
}This error message is returned with a 403 HTTP status code when you exceed the free tier with no payment method on file:
{
"error": "You can't make this request as it is above your daily maximum. You can configure billing at https://dash.geocod.io"
}The Geocodio API employs semantic HTTP status codes:
| Error Code | Meaning |
|---|---|
| 200 OK | Hopefully you will see this most of the time. Note that this status code will also be returned even though no geocoding results were available. |
| 403 Forbidden | Invalid API key, or other reason why access is forbidden. |
| 422 Unprocessable Entity | A client error prevented the request from executing successfully (e.g. invalid address provided). A JSON object will be returned with an error key containing a full error message. |
| 429 Too Many Requests | You've reached the Pay as You Go rate limit. Please inspect the following HTTP headers: X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Period and stop making requests until the end of the X-RateLimit-Period value. |
| 500 Server Error | Hopefully you will never see this...it means that something went wrong in our end. Whoops. |
If you encounter any unexpected errors, please check status.geocod.io for the latest platform status updates.
The Geocodio API implements the concept of "warnings". This is meant to assist and guide developers when implementing our API.
Warnings are represented with a _warnings key, and it can be applied to either an individual geocoding result or an overall geocoding query.
If no warnings have been triggered, the _warnings key will not be part of the JSON output at all.
Here's an example where the query parameter
postalcodeaccidentally was used instead ofpostal_code
{
"input": {
...
},
"results": [
...
],
"_warnings": [
"Ignoring parameter \"postalcode\" as it was not expected. Did you mean \"postal_code\"? See full list of valid parameters here: https://www.geocod.io/docs/"
]
}Warnings can also be triggered for individual results, such as when an ACS field append was specified for a city-level query:
{
"input": {
...
},
"results": [
{
...
"_warnings": [
"acs-demographics was skipped since result is not street-level"
]
}
]
}To Geocode an address using a jQuery AJAX call.
<script>
var address = '1109 N Highland St, Arlington VA',
apiKey = 'YOUR_API_KEY';
$.get('https://api.geocod.io/v1.7/geocode?q='+ encodeURIComponent(address) +'&api_key=' + encodeURIComponent(apiKey), function (response) {
console.log(response.results);
});
</script>The Geocodio API supports CORS using the Access-Control-Allow-Origin HTTP header. This means that you will be able to make requests directly to the API using JavaScript.
(See an example to the right.)
Note: This will expose your API Key publicly, make sure that you understand and accept the implications of this approach.The Geocodio API is continuously improved. Most updates require no changes for API users, but in some cases we might have to introduce breaking changes.
Breaking changes are introduced with new API versions, allowing you to "upgrade" to the newest version at your own pace. Older API versions are guaranteed to be available for at least 12 months after they have been replaced by a newer version, but may be supported for longer.
Major changes, that are not breaking are also documented here.
Breaking changes are defined as changes that remove or rename properties in the JSON output of any API endpoint. Your API client should be able to gracefully support addition of new JSON properties, as this is not considered a breaking change.Released on December 16, 2024
- The
cd119field append has been added, for the 119th congress. This will be the new default congressional district append, starting on January 3rd, 2025.
Released on November 4, 2024
- The
zip4field append now returns a residential delivery indicator (RDI) with the newresidentialproperty.
Released on September 27, 2024
- The
provriding-nextdata append is now available. Upcoming provincial ridings for Saskatchewan can be previewed. Theprovridingwill be returning these new ridings as of 10/28/2024.
Released on September 20, 2024
provriding: New district boundaries are now used for British Columbia
Released on April 29, 2024
stateleg-next: Upcoming districts boundaries were added for Minnesota House & Senate districts, they will be promoted tostatelegon 1/14 2025
Released on April 24, 2024
- Added Census County Subdivisions to the
censusfield append
Released on April 16, 2024
cd118: District boundaries were updated for North Carolina, Louisana and New Yorkstateleg: Wisconsins and Michigan House district boundaries were updated. New Mexico Senate district boundaries were updated.stateleg-next: Upcoming districts boundaries were added as follows:- New York Assembly districts, will be promoted to
statelegon 1/1 2025 - Ohio House & Senate districts, will be promoted to
statelegon 1/1 2025 - Washington House & Senate districts, will be promoted to
statelegon 8/6 2024
- New York Assembly districts, will be promoted to
Released on April 8, 2024
- Introduced the
riding-nextwhich allows federal electoral district lookups in Canada, based on redistricting ridings
Released on January 18, 2024
- Introduced
census2023data append (thecensusdata append will now default tocensus2023) - Corrected an issue where census field appends always returned county FIPS codes for most recent census year. This primarily affects census county lookups in Connecticut as this state switched to a new county-equivalent system as of the 2022 census release.
Released on November 8, 2023
- Updated state legislative districts for North Carolina
Released on August 14, 2023
- Corrected an issue that caused batch geocoding requests to only return results from the first country when addresses from mixed countries were present in a single batch. The original issue was inadvertently introduced on July 24th.
Released on April 26, 2023
- Added upcoming redistricted boundaries for Montana with the
stateleg-nextdata append - Corrected boundaries current senate state legislative districts for California. Districts with odd numbers were incorrectly using upcoming boundaries. Geocodio is now applying special logic required due to partial redistricting. You can read more here.
- Updated Statistics Canada data to latest 2021 census release. The following additional values has been added as well:
- Designated place
- Population centre
- Dissemination area
- Dissemination block
Released on March 14, 2023
- Updated Alaska state legislative district boundaries
Released on February 7, 2023
- Corrected version of state legislative districts returned for:
- NM State Senate. New districts will be returned when the next session commences 1/21/2025
- KS State Senate. New districts will be returned when the next session commences 1/15/2025
- SC State Senate. New districts will be returned when the next session commences 1/7/2025
- Redistricted state boundaries can still be requested early by using the
stateleg-nextdata append
Released on February 1, 2023
Corrected version of state legislative districts returned for New Mexico Senate. New districts will be returned when the next session commences 1/21/2025, or using the(This was rolled back and postponed to February 7th)stateleg-nextdata append.- Corrected the following Massachusetts state legislative district OCD ids:
- Changed "ocd-division/country:us/state:ma/sldu:berkshire_hampshire_franklin_and_hampden" to "ocd-division/country:us/state:ma/sldu:berkshire_hampden_franklin_and_hampshire"
- Changed "ocd-division/country:us/state:ma/sldu:1st_hampden_and_hampshire" to "ocd-division/country:us/state:ma/sldu:hampden_and_hampshire"
- Changed "ocd-division/country:us/state:ma/sldu:1st_middlesex_and_norfolk" to "ocd-division/country:us/state:ma/sldu:middlesex_and_norfolk"
- Changed "ocd-division/country:us/state:ma/sldu:norfolk_bristol_and_plymouth" to "ocd-division/country:us/state:ma/sldu:norfolk_plymouth_and_bristol"
Released on January 23, 2023
- Updated congressional district and state legislative district boundaries for Wisconsin
- Corrected an issue where 4th Middlesex and 5th Middlesex in Massachusetts was returning an incorrect OCD id
Released on January 17, 2023
- Census ACS data has been updated to the latest release (2021 ACS data)
- The
ocd_idvalue is now set for allstatelegdistrict result (previously, it wasnullfor pre-redistricting districts)
Released on January 11, 2023
- Introduced
census2022data append (thecensusdata append will now default tocensus2022) statelegdata append now returns redistricted boundaries for all states except MS, NJ, LA, MT and VA. For these states, usestateleg-nextto get redistricted data instead
Released on May 19, 2022
- The
stateleg-nextandcd118field appends now return OCD identifiers
Released on March 7, 2022
- When using the
stateleg-nextdata append, theis_upcoming_state_legislative_districtproperty will now returnfalsein cases where the state's data has not been updated yet
Released on February 11, 2022
- Added the new
provridingfield append for provincial/territorial legislative districts in Canada
Released on February 10, 2022
- The
cd118andstateleg-nextdata appends has been updated with the addition of updated districts for California, Massachusetts and Virginia
Released on January 17, 2022
- Introduced
census2021data append (thecensusdata append will now default tocensus2021)
Released on January 13, 2022
- Introduced
census2000data append for 2000 vintage census boundaries - Updated
cd118andstateleg-nextdata appends with data for additional redistricted states
Released on November 12, 2021
- Breaking: The
state_legislative_districtskey from thestatelegfield append now returns an array ofhouseandsenatedistricts instead of a single object - The
stateleg-nextfield append is back! Now returning a preview from upcoming state legislative district changes. As with congressional districts, we are updating district data on an ongoing basis as more states complete their redistricting process statelegandstateleg-nextcan now return all districts that intersect with a zip code boundary along with the proportion of overlapcd118has been added as a field append, returning districts for the upcoming 118th congress. Districts are updated on an ongoing basis as more states complete their redistricting process
Released on September 15, 2021
Released on June 16, 2021
- Counties can now be geocoded in the U.S. Either standalone, or as part of an adddress
Released on March 1, 2021
statelegnow returns the same data asstateleg-next.stateleg-nextmay be used again for future legislative district changes
Released on February 25, 2021
- Introduced
census2020data append (thecensusdata append will now default tocensus2020) - Update all Census ACS data to most recent 5-year release (2015-2019)
Released on May 28, 2020
- Breaking: This fixes a bug which has backwards-incompatible consequences for
acs-familiesandacs-demographicsfield appends - Non-breaking: The
acs-socialtable, Population with veteran status (Table B21001) now includes age breakdowns
The following ACS data tables have titles changed and/or values corrected:
acs-families
- Household type by household (Table B11001)
- Household type by population (Table B11002)
- Marital status (Table B12001)
acs-demographics
- Race and ethnicity (Table B03002)
Released on May 13, 2020
- Breaking: PO Box and second address lines (e.g. apartment/unit/suite numbers) are now returned as
resultsand appear within theformatted_addresskeys - The
zip4data append is now generally available
Released on September 18th, 2019
census appends:
- Breaking: The
censusappend now supports vintage years, data is keyed by year instead of just returning a single year
Released on March 12th, 2018
timezone appends:
- Breaking:
nameproperty has been renamed toabbreviation nameis now the full timezone name in a tzdb-compatible format. Read more
Released on January 20th, 2018
cd (Congressional district) appends:
- Breaking:
current_legislatorproperty has been renamed tocurrent_legislatorsand is now an array instead of an object - Both house and senate legislators are now returned
Released on January 8th, 2018
cd (Congressional district) appends:
- Breaking:
congressional_districtproperty has been renamed tocongressional_districts - Breaking: Postal code lookups will now return multiple Congressional districts if the zip code area spans more than one district
- Current legislator information is now returned with Congressional districts
Have any questions? Feel free to tweet us @Geocodio or shoot us an email [email protected].
If you find an error in the documentation or want something to be clarified, please create a pull request or issue so we can correct it.