loginaboutcontributeblogfeedback

About our API

Making the data collected here useful to other developers is a core part of our mission. That's why we've made sure that every part of the site is not just human-readable but also machine-readable.

Content

You'll notice at the bottom of most pages, there's a note for developers that links to a version of the page in a variety of machine-readable formats:

  • N3: (aka Notation3, Turtle, N-Triples Plus, etc.) text/rdf+n3

    This elegant text-based RDF format is our recommended method for getting our data. Most modern languages have an RDF toolkit that can parse and query against N3 inputs. For more information, visit rdfabout.

  • JSON: (aka JavaScript Object Notation) application/json

    JSON is a simple text-based format for transporting objects. Most modern langauges have a JSON library that converts it into objects in your native language. For more information, visit JSON.org.

  • XML: (aka RDF/XML) application/rdf+xml

    We use a constrained version of XML called RDF/XML that simplifies parsing and allows us to annotate values with their datatypes. Again, using an RDF library may make this format easier to parse.

Are there other formats you'd like? Let us know.

To get at these formats, you can either add .n3 or the appropriate file suffix to the end of the URL (for example, http://watchdog.net/us/ak-00.n3) or you can request the page with an HTTP Accept: header that specifies the media type for the format you want. (The media types we use are listed next to the format name above.)

Here's an example using the command-line HTTP client curl:

  $ curl -s http://watchdog.net/us/ak-00 | head
  <html>
  <head>
    <title>AK-00: Alaska’s at-large congressional district (watchdog.net)</title>
  [...]
  
  $ curl -s http://watchdog.net/us/ak-00.n3 | head
  @prefix : <http://watchdog.net/about/api#> .

  <http://watchdog.net/us/AK-00> a :District;
    :almanac <http://nationaljournal.com/pubs/almanac/2008/people/ak/rep_ak01.htm>;
    :area_sqmi 663267;
  [...]
  
  $ curl -s -H "Accept: application/json" http://watchdog.net/us/ak-00 | head
  [
    {
      "almanac": "http://nationaljournal.com/pubs/almanac/2008/people/ak/rep_ak01.htm", 
      "area_sqmi": 663267, 
      "center_lat": 65.831199999999995, 
  [...]

States

You can get at states through URLs of the form http://watchdog.net/us/va -- there you'll find all the information we have on a given state.

Districts

Districts have URLs of the form http://watchdog.net/us/va-01 where at-large districts have the number suffix -00.

For a full list of districts (although not everything we have on each district) visit http://watchdog.net/us/

Politicians

Politicians have URLs of the form http://watchdog.net/p/nancy_pelosi

A full list of politicians (although not everything we have on each of them) can be found at http://watchdog.net/p/

Queries

zip2rep / zip2dist

A common problem developers have is figuring out which congressional district the user is located in. Because congressional districts change frequently and are heavily gerrymandered this is a rather difficult problem.

We provide a simple API for solving this: Give us a zip code or zip+4 and we'll give you back all the matching Congressional districts. Give us a zip code and an address and we'll give you back just the one that matches.

You can do these queries via URLs like http://watchdog.net/us/?zip=90210
http://watchdog.net/us/?zip=90210-5106
and http://watchdog.net/us/?address=360+N+Rodeo+Dr&zip=90210

Unfortunately, we don't currently have fully machine-readable output for these queries. We're still thinking about the right way to do design the API. If you need this, let us know.

For the source code and data, see the files zip2rep.py and zipdict.txt in our utils directory.

The zip+4 information comes from the USPS and is available in TSV format in our zip4.tsv file.

index