Differences between the API and MongoDB

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.

Legislator Lookup

• No discernible difference

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

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 the format YYYY-MM-DD, defaults to a week ago
• dtend: search for events with a when before dtstart, in the format YYYY-MM-DD
• 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!