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

• 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

Legislators

• By default, removes roles, old_roles and sources

Committees

Committee Search

• By default, returns only id, state, chamber, committee, subcommittee, parent_id, created_at and updated_at. To get all the fields except for +plus fields and country and level (which are always us and state if set), use:

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

Committee Lookup

• No discernible difference

Districts

District Search

• Adds a legislators field with an array of objects 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!