README

Congressional District Finder

A small library of functions for determining US Congressional representation based on location.

Fetches and parses data from:

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 = require('congressional-district-finder');

finder.getDistrictByLatLng(40.718031, -73.9583047)
    .then(function(result) {
        console.log(result.isMatched); // outputs true
        console.log(result.district.name); //outputs "New York 12th"
        console.log(result.district.districtCode); //outputs "NY-12"
    });

If coordinates are outside the US:

finder.getDistrictByLatLng(31.6538179, -106.5890206)
    .catch(function(err) {
        console.log(err.message);
        // Outputs:
        //      "The specified latitude: 31.6538179 and longitude: -106.5890206
        //       are for the country: MX. To Find a Congressional District,
        //       please provide coordinates in the US."
    });

Get a District by Address

finder.getDistrictByAddress('45 Main Street Brooklyn')
    .then(function(result) {
        console.log(result.isMatched); // outputs true
        console.log(result.district.name); //outputs "New York 7th"
        console.log(result.district.districtCode); //outputs "NY-07"
    });

If the address is too vague:

finder.getDistrictByAddress('Pittsburgh, PA')
    .catch(function (err) {
        console.log(err.statusCode); //outputs 400
        console.log(err.message);
        // Outputs:
        //      "The specified address: ''Pittsburgh, PA'' appears to be too vague.
        //       Try including a street name and number."
    });

If the address is outside the US:

finder.getDistrictByAddress('3895 Boulevard St-Laurent, Montreal')
    .catch(function (err) {
        console.log(err.statusCode); //outputs 404
        console.log(err.message);
        // Outputs:
        //      "The specified address: '3895 Boulevard St-Laurent, Montreal'
        //       appears to be from the country: CA. To find a Congressional District,
        //       please provide coordinates in the US. More specific coordinates might also work."
    });

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.getDistrictByAddress('1600 Pennsylvania Avenue DC')
    .catch(function(err) {
        if (err.message === finder.DISTRICT_NOT_FOUND('DC-0')) {
            throw new Error('Taxation without representation.');
        }
        throw err;
    })
    .catch(function(err) {
        console.log(err.message); // Outputs: "Taxation without representation."
    });

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.getDistrictByAddress(address)
    .catch(function(err) {
        if (err.statusCode != 404) {
            throw err;
        }
        switch (err.message) {
            case finder.ADDRESS_OUTSIDE_US(address, 'PR') :
            return Promise.resolve({
                district: {
                    districtCode: 'PR-AL',
                    name: 'Puerto Rico At-Large'
                }
            });
            default:
                throw err;
        }
    })
    .then(function(result) {
        console.log(result.district.name); // Outputs "Puerto Rico At-Large"
    });

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.getDistricts()
    .then(function(result) {
        console.log(result.districts.length); // outputs all 435 US Congressional Districts
        console.log(result.districts[0]);// outputs AK-0
        console.log(result.districts[434]);// outputs WY-0
    });

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.getDistricts({'If-None-Match': myCachedEtag})
    .then(function(result) {
        //update your cached etag and cached list of districts
        myCachedEtag = result.headers.etag;
        districts = result.districts;
        console.log(myCachedEtag);
    })
    .catch(function(err) {
        if (err.statusCode === 304) {
           console.log('just use your cached districts.');
        }
    });

Check Coordinates Against a State

fetches GEOJson from github/unitedstates
parses and checks the coordinates using geolib

var lat = 40.718031;
var lng = -73.9583047;

finder.checkLatLngInState(lat, lng, 'NY')
    .then(function(result) {
        console.log('Check coordinates in New York...');
        console.log(result); // outputs { isMatched: true, stateId: 'NY', latitude: 40.718031, longitude: -73.9583047 }
    });

finder.checkLatLngInState(lat, lng, 'CT')
    .then(function(result) {
        console.log('Check coordinates in Connecticut...');
        console.log(result); // outputs {isMatched: false, stateId: 'CT',latitude: 40.718031, ongitude: -73.9583047 }
    });

Check Coordinates Against a District

fetches GEOJson from github/unitedstates
parses and checks the coordinates using geolib

var honolulu = {latitude: 21.3069, longitude: -157.8583};

finder.checkLatLngInDistrict(honolulu.latitude, honolulu.longitude, 'HI-1')
    .then(function(result) {
        console.log(result.districtId); // outputs HI-1
        console.log(result.district.districtCode); // outputs HI-01
        console.log(result.district.name); // outputs Hawaii 1st
        console.log(result.isMatched); // outputs true
        console.log('-');
    });

finder.checkLatLngInDistrict(honolulu.latitude, honolulu.longitude, 'HI-2')
    .then(function(result) {
        console.log(result.districtId); // outputs HI-2
        console.log(result.district.districtCode); // outputs HI-02
        console.log(result.district.name); // outputs Hawaii 2nd
        console.log(result.isMatched); // outputs false
        console.log('-');
    });

Tests

$ npm test

Contributing

Code is transpiled from ES6/ES2015. You can lint code by running:

$ npm run lint

Usage no npm install needed!