yourstate.us
Home / API

The yourstate.us API

The data behind the site’s pages, as JSON, for your own software. Free for 5,000 calls a month.

Get a key

  1. Make an account and confirm your email address from the link we send.
  2. On your profile, under API, choose Make an API key. It is shown once; copy it then. You can hold three at a time and revoke any of them.
  3. Send it with each call: Authorization: Bearer ysk_…

Signed in, you can also open any “Get this as JSON” link in your browser without a key. Both count against the same 5,000.

Make a call

Put /api/v1 in front of the path of any page that shows “Get this as JSON”. The JSON holds the same figures as that page’s Download report, and takes the same query parameters: parts= to choose sections, from= and to= for years, ind= for indicators.

curl -H "Authorization: Bearer $YOURSTATE_KEY" \
  https://yourstate.us/api/v1/provision/74
PageJSON atWhat you get
/provision/<id>/api/v1/provision/74A provision's text, citation, status, version, cite ID and SHA-256 hash.
/vote/<id>/api/v1/vote/49009A roll-call vote from 1989 on: question, result, tallies, every member's position, cite ID and hash.
/member/<bioguide-id>/api/v1/member/P000197A member's terms, the figures measured on the districts they represented, and their votes from 1989 on.
/district/<code>/api/v1/district/TX-23A congressional district's indicators and who has held it.
/districts/<state>/api/v1/districts/TXA state's indicators and its seats' history.
/indicator/<code>/api/v1/indicator/median_hh_incomeOne measure ranked across districts.
/indicator/<code>/states/api/v1/indicator/median_hh_income/statesOne measure ranked across states.
/national/api/v1/nationalNational figures and the economy.
/economy/<code>/api/v1/economy/unemployment_rateOne economic measure over time.
/spending and /spending/…/api/v1/spending/state/TXFederal spending by agency, function, state, country and recipient, as on those pages.

What comes back

Every answer is { data, source, attribution, api_version, usage }. source is the page the data is from. For a provision or a vote, data is a single record with its cite_id and sha256 (see checking a citation). For every other page it is the page’s report: a title, meta lines, and sections, each a table (named columns and rows, with truncated set when rows were cut), a list of facts, or prose, then notes on sources and caveats. Keep the notes with the figures; they say what each one is.

Limits

  • 5,000 calls per account per calendar month (UTC), across all of its keys. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
  • At most 60 calls a minute.
  • Over either, you get 429 with Retry-After. Errors are JSON with an error code and a message: 401 api_key_required or invalid_key, 403 email_not_confirmed or not_served, 404 not_found, 400 bad_request, 429 too_fast or monthly_limit.

A card instead of data

To show a vote, a member, a district or a law on a web page rather than use its data in software, there is no key to get: put /embed in front of the page’s path, or use the widget builder. Widgets leave out the same things the API does.

What the API does not serve

The site shows all of these; the API leaves them out on purpose, and answers 403 not_served with the reason:

  • Financial disclosures. Federal law (5 U.S.C. 13107(c)) restricts use of disclosure reports for commercial purposes other than by the news media.
  • Campaign-finance detail (a member’s contributors, donors, candidates), while the rule on use of FEC contributor information (52 U.S.C. 30111(a)(4)) is reviewed.
  • Roll calls before 1989, which come only from a source whose licence has not been reviewed. A member file starts at 1989 for the same reason.
  • Member biographies (Wikipedia text) and the Democratic–Republican scale.

Using the data

  • Name yourstate.us and link to the source page wherever you show the data.
  • Laws are reproduced as published and are not legal advice; a summary, where there is one, is generated by an AI model.
  • The terms of service apply, and the neutrality charter says how the site treats every side.