Skip to content
This repository has been archived by the owner on Feb 1, 2020. It is now read-only.

Differences between the API and MongoDB

Jump to bottom
jpmckinney edited this page Apr 30, 2013 · 13 revisions

The JSON downloads are in the same format as the API and are usually created on the first day of each month with the billy-util dumpjson command without the --novalidate switch. You can get the date and URL of the latest JSON dump of each state via the API, for example:

http://openstates.org/api/v1/metadata/?fields=latest_json_url,latest_json_date&apikey=API_KEY

General differences between the API and MongoDB

  • Renames _id to id
  • All underscore fields like _all_ids are not available
  • Votes are available through bills
  • Subjects are not available

When returning multiple documents, the API may return a subset of all fields. Add fields using the fields query string parameter.

Metadata

Metadata Overview

  • By default, returns only abbreviation, name, chambers and feature_flags. To get all the fields except for plus fields, use:

      fields=id,abbreviation,name,chambers,feature_flags,legislature_name,legislature_url,capitol_timezone,latest_update,terms,session_details,latest_json_url,latest_json_date,latest_csv_url,latest_csv_date,capitol_maps

  • Adds top-level fields like lower_chamber_name for backwards compatibility

Metadata Lookup

  • No discernible difference

Bills

TODO

Legislators

Legislator Search

  • By default, removes roles, old_roles and sources. To get all the fields except for plus fields, leg_id (which is always equal to _id), created_at (updated_at is better), and country and level (which are always us and state if set), use:

      fields=active,state,chamber,district,party,full_name,first_name,middle_name,last_name,suffixes,email,url,photo_url,transparencydata_id,votesmart_id,roles,old_roles,offices,sources,updated_at

  • If the term and active query string parameters aren't set, the API will limit results to legislators for which active is true. You can remove the active filter by setting the active query string parameter to anything but true, e.g. active=x.

Legislator Lookup

  • No discernible difference (used by JSON downloads)

Legislator Geo Lookup

  • Adds boundary_id, unless the district name is At-Large

Note: The API always returns state, chamber and district, no matter what the value of the fields query string parameter.

Committees

Committee Search

  • By default, removes members and sources. To get all the fields except for plus fields, created_at (updated_at is better) and country and level (which are always us and state if set), use:

      fields=parent_id,state,chamber,committee,subcommittee,updated_at,members,sources

Committee Lookup

  • No discernible difference (used by JSON downloads)

Districts

The Districts API allows searches within a single jurisdiction at a time.

District Search

  • Adds a legislators field with an array of active legislators with leg_id and full_name fields

District Boundary Lookup

  • Adds bbox, region and shape fields

Events

The Events API lacks the following documentation:

  • dtstart: search for events with a when after dtstart, in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format, defaults to a week ago
  • dtend: search for events with a when before dtstart, in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format
  • A maximum of 1000 events are returned

In order to retrieve all events, you must change the size of the time window set by dtstart and dtend until under 1000 events are returned, then proceed to the next time window and repeat. The first window is dtstart=1900-01-01&dtend=2010-12-01. Good luck!

Clone this wiki locally