Fork me on GitHub
Loading...

Boundary Location API

As an experimental service, we are providing an API which can identify the Census geographies which contain a given point (latitude/longitude). We have not done substantial performance benchmarking with this service, and reserve the right to impose access restrictions or disable the service completely if Boundary Location API requests adversely impact the performance of other aspects of the Census.IRE.org application.

As with other areas of this application, a limited subset of Census geographies are supported, specifically: state, county, county subdivision, place, and census tract.

With the boundary and GeoID data returned from this service, one can subsequently retrieve all Census SF-1 data for the given shape using our JSON data API.

Exact geographies

Given a GeoID, the GeoJSON for the corresponding geography can easily be retrieved. The GeoID must be qualified by the geography type. The basic format for the URL is http://census.ire.org/geo/1.0/boundary-set/geography-type/geoid

The available types are:

For example, to get the boundary of the state of Illinois, use http://census.ire.org/geo/1.0/boundary-set/states/17, or for the city of Chicago, use http://census.ire.org/geo/1.0/boundary-set/places/1714000

Point queries

The fundamental query exposed by the Boundary Service is a point-in-polygon search by latitude and longitude. Here is an example:

http://census.ire.org/geo/1.0/boundary/?contains=38.948337,-92.328032&sets=tracts,counties

This will return the census tract and county which contain the IRE central office.

Note: In addition to the contains parameter we also pass the sets parameter to constrain the query. Where possible, please use this parameter to limit your queries to only the data you need so your queries will be performant. Valid values for sets are one or more of the following:

Near queries

The near query finds all Boundaries that intersect a circle of a specified radius using a given point as its center:

http://census.ire.org/geo/1.0/boundary/?near=38.948337,-92.328032,1mi&sets=tracts

This returns all wards within one mile of the IRE central office. The radius parameter may be specified in any units supported by GeoDjango.

Note: This query will execute more slowly than the point query.

JSONP

For use in client-side applications the Boundary Service API may be accessed via JSONP. Simply append the format and callback parameters to the query string:

http://census.ire.org/geo/1.0/boundary/?contains=38.948337,-92.328032&sets=tracts&format=jsonp&callback=func

Hosting your own service

If performance is critical, or should we find it necessary to limit access to this API, it should be relatively straightforward to set up your own boundary service. The code is open-source, and can be downloaded from https://github.com/newsapps/django-boundaryservice . The "definitions" file we use, which is required by the Boundary Service code, can be downloaded from the IRE Census Github repository.