/
api.html
77 lines (47 loc) · 3.84 KB
/
api.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{% extends "flat/flatpage.html" %}
{% load markup_tags %}
{% block title %}Open States API{% endblock %}
{% block breadcrumb %}
{% endblock %}
{% block flatpage %}
<h2> Open States API </h2>
{% rest %}
The Open States provides a RESTful API for accessing state legislative information.
* API calls are URLs in the form ``http://openstates.org/api/v1/METHOD/?apikey=``
* Responses will (unless otherwise specified) be `JSON <http://json.org/>`_.
* If an error occurs the response will be a plain text error message with an appropriate HTTP error codes are sent on errors (404 if object is not found, 401 if authentication fails, etc.).
* The required API key can be obtained via http://services.sunlightlabs.com/
* For details on the current availability and status of state data visit the `Open States status page <http://openstates.org/status/>`_.
All changes to the API will be announced on the `Open States Google Group <http://groups.google.com/group/fifty-state-project/>`_ and documented in the `api changelog </api/changelog/>`_.
Client Libraries
================
* We make an official `python-sunlight <http://python-sunlight.readthedocs.org>`_ library available that supports our API.
* There's also a `govkit ruby gem <https://github.com/opengovernment/govkit>`_ that interfaces with the Open States API as well as many others.
Methods
=======
There are five top level object types Metadata, Bills, Legislators, Committees, and Events.
With the exception of metadata, all have a generic search method and a direct lookup method.
{% endrest %}
{% include "flat/api/api_methods.html" %}
{% rest %}
Requesting A Custom Fieldset
============================
It is possible to return a custom subset of fields on an object by specifying a special ``fields`` parameter.
There are two use cases that this functionality aims to serve:
First, if you are writing an application that loads a lot of data but only uses some of it, specifying a limited subset of fields can reduce response time and bandwidth. We've seen this approach be particuarly useful for mobile applications where bandwidth is at a premium.
An example would be a legislator search with ``fields=first_name,last_name,leg_id`` specified. All legislator objects returned will only have the three fields that you requested.
Second, you can actually specify a set of fields that includes fields excluded in the default response.
For instance if you are doing a bill search it typically does not include sponsors, though many sites may wish to use sponsor information without making a request for the full bill (which is typically much larger as it includes versions, votes, actions, etc.).
A bill search that specifies ``fields=bill_id,sponsors,title,chamber`` will include the full sponsor listing in addition to the standard bill_id, title, and chamber fields.
Extra Fields
============
You may notice that the fields documented are sometimes a subset of the fields actually included in a response.
Many times as part of our scraping process we take in data that is available for a given state and is either not available or does not have an analog in other states. Instead of artificially limiting the data we provide to the smallest common subset we make this extra data available.
To make it clear which fields can be relied on and which are perhaps specific to a state or subset of states we prefix non-standard fields with a ``+``.
If you are using the API to get data for multiple states it is best to restrict your usage to the fields documented here, if you are only interested in data for a small subset of our available states it might make sense to take a more in depth look at the API responses for the state in question to see what extra data we are able to provide.
{% endrest %}
{% endblock %}
{% block flatpage_right %}
<h3 class="apibar">API Methods</h3>
{% include "flat/api/api_methods.html" %}
{% endblock %}