Congressional District Finder
A small library of functions for determining US Congressional representation based on location.
Fetches and parses data from:
- https://github.com/unitedstates/districts/
- http://www.house.gov/
- http://maps.googleapis.com/maps/api/geocode/json
And uses geolib to determine if a given latitude or longitude resides in a state or district's geoJSON boundaries.
None of these require API tokens but getDistricts fetches from the Github Contents API, which rate-limits unauthenticated requests to 60 per hour from a given IP.
Requirements
Requires NodeJS version 4 or greater.
Installation
$ npm install congressional-district-finder --save
Usage
All methods return promises, using Request-Promise-Native for various http GET requests.
Get a District by Latitude and Longitude
var finder = ; finder ;
If coordinates are outside the US:
finder ;
Get a District by Address
finder ;
If the address is too vague:
finder ;
If the address is outside the US:
finder ;
Handling the 404 for DC and Puerto Rico's At-Large Districts
Currently the repository of GeoJSON for 2016 congressional districts doesn't contain a district shape for DC's at-large district (DC-0 or DC-AL). To handle this situation, you can check the message on a 404 response against the template used to format the message for this particular error.
finder ;
Since DC is an at-large district, it's safe to assume that the provided coordinates reside in this district.
Likewise, because it's a territory, Puerto Rico will also throw a 404. While Puerto Rico's at-large district is also missing from the 2016 GEOJson repo, this particular error is thrown because it doesn't reside in the US. It can be detected and handled as such:
var address = 'San Juan, Puerto Rico';finder ;
Error templates are also exported for COORDS_OUTSIDE_US: 404, and ADDRESS_TOO_VAGUE: 400.
Other Methods
Get a List of All US Congressional Districts
finder ;
Note that this particular method uses the Github Contents API Without Github API auth credentials, you are limited to 60 requests per hour from a given IP. If your application will likely exceed this, you can do the following:
- Increase your rate limit by passing auth credentials via the customHeaders.
- Cache the result and verify that it's up to date by passing an etag or last modified time stamp.
var districts myCachedEtag = '"36bac568759f240e06955cf597493555"';finder ;
Read more about Github's rate limit rules.
Check Coordinates Against a State
- fetches GEOJson from github/unitedstates
- parses and checks the coordinates using geolib
var lat = 40718031;var lng = -739583047; finder ; finder ;
Check Coordinates Against a District
- fetches GEOJson from github/unitedstates
- parses and checks the coordinates using geolib
var honolulu = latitude: 213069 longitude: -1578583; finder ; finder ;
Tests
$ npm test
Contributing
Code is transpiled from ES6/ES2015. You can lint code by running:
$ npm run lint