diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..15806e4 --- /dev/null +++ b/404.html @@ -0,0 +1,945 @@ + + + +
+ + + + + + + + + + + + + + + +Changelog for Open States GraphQL API:
+Initial draft release of the API, no backwards-compatibility guarantee +made.
+ + + + + + +{
+ jurisdictions {
+ edges {
+ node {
+ name
+ legislativeSessions {
+ edges {
+ node {
+ name
+ }
+ }
+ }
+ legislature: organizations(classification: "legislature", first: 1) {
+ edges {
+ node {
+ name
+ classification
+ children(first: 5) {
+ edges {
+ node {
+ name
+ classification
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
{
+ jurisdiction(name: "North Dakota") {
+ name
+ url
+ legislativeSessions {
+ edges {
+ node {
+ name
+ identifier
+ }
+ }
+ }
+ organizations(classification: "legislature", first: 1) {
+ edges {
+ node {
+ id
+ name
+ children(first: 20) {
+ edges {
+ node {
+ name
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
{
+ search_1: bills(first: 5, jurisdiction: "New York", session: "2017-2018", chamber: "lower", classification: "resolution", updatedSince: "2017-01-15") {
+ edges {
+ node {
+ id
+ identifier
+ title
+ classification
+ updatedAt
+ createdAt
+ legislativeSession {
+ identifier
+ jurisdiction {
+ name
+ }
+ }
+ actions {
+ date
+ description
+ classification
+ }
+ documents {
+ date
+ note
+ links {
+ url
+ }
+ }
+ versions {
+ date
+ note
+ links {
+ url
+ }
+ }
+
+ sources {
+ url
+ note
+
+ }
+ }
+ }
+ }
+}
+
{
+ b1: bill(jurisdiction: "Hawaii", session: "2017 Regular Session", identifier: "HB 475") {
+ id
+ identifier
+ title
+ classification
+ updatedAt
+ createdAt
+ legislativeSession {
+ identifier
+ jurisdiction {
+ name
+ }
+ }
+ actions {
+ date
+ description
+ classification
+ }
+ documents {
+ date
+ note
+ links {
+ url
+ }
+ }
+ versions {
+ date
+ note
+ links {
+ url
+ }
+ }
+ sources {
+ url
+ note
+ }
+ }
+ b2: bill(id: "ocd-bill/9c24aaa2-6acc-43ad-883b-ae9f677062e9") {
+ id
+ identifier
+ title
+ classification
+ updatedAt
+ createdAt
+ legislativeSession {
+ identifier
+ jurisdiction {
+ name
+ }
+ }
+ actions {
+ date
+ description
+ classification
+ }
+ documents {
+ date
+ note
+ links {
+ url
+ }
+ }
+ versions {
+ date
+ note
+ links {
+ url
+ }
+ }
+ sources {
+ url
+ note
+ }
+ }
+}
+
{
+ person(id:"ocd-person/dd05bd23-fe49-4e65-bfff-62db997e56e0"){
+ name
+ contactDetails {
+ note
+ type
+ value
+ }
+ otherNames {
+ name
+ }
+ sources {
+ url
+ }
+ currentMemberships {
+ organization {
+ name
+ }
+ }
+ }
+}
+
ocd-organization/ddf820b5-5246-46b3-a807-99b5914ad39f
is the id of the
+Alabama Senate chamber.
{
+ people(memberOf:"ocd-organization/ddf820b5-5246-46b3-a807-99b5914ad39f", first: 100) {
+ edges {
+ node {
+ name
+ party: currentMemberships(classification:"party") {
+ organization {
+ name
+
+ }
+ }
+ links {
+ url
+ }
+ sources {
+ url
+ }
+ chamber: currentMemberships(classification:["upper", "lower"]) {
+ post {
+ label
+ }
+ organization {
+ name
+ classification
+ parent {
+ name
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
{
+ people(latitude: 40.7460022, longitude: -73.9584642, first: 100) {
+ edges {
+ node {
+ name
+ chamber: currentMemberships(classification:["upper", "lower"]) {
+ post {
+ label
+ }
+ organization {
+ name
+ classification
+ parent {
+ name
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
As of December 1, 2023, the v2/GraphQL API has been sunset. Please +migrate to the v3 API as soon as possible. Future service for the GraphQL API +is not guaranteed.
+The rest of this documentation is left up for reference.
+X-API-KEY
header.This is a GraphQL API, and some of the concepts +may seem unfamiliar at first.
+There is in essence, only one endpoint: +https://openstates.org/graphql.
+This endpoint, when accessed in a browser, will provide an interface +that allows you to experiment with queries in the browser, it features +autocomplete and a way to browse the full graph (click the \'Docs\' link +in the upper right corner).
+A GraphQL query mirrors the structure of the data that you\'d like to +obtain. For example, to obtain a list of legislators you\'d pass +something like:
+{
+ people {
+ edges {
+ node {
+ name
+ }
+ }
+ }
+}
+
Note
+If you are using the API programatically it is recommended you send the +data as part of the POST body, e.g.:
+curl -X POST https://openstates.org/graphql -d "query={people{edges{node{name}}}}"
Of course, if you try this you'll see it doesn't work since there are
+some basic limits on how much data you can request at once. We paginate
+with the first
, last
, before
and after
parameters to a root
+node. So let's try that again:
{
+ people(first: 3) {
+ edges {
+ node {
+ name
+ }
+ }
+ }
+}
+
And you'd get back JSON like:
+{
+ "data": {
+ "people": {
+ "edges": [
+ {
+ "node": {
+ "name": "Lydia Brasch"
+ }
+ },
+ {
+ "node": {
+ "name": "Matt Williams"
+ }
+ },
+ {
+ "node": {
+ "name": "Merv Riepe"
+ }
+ }
+ ]
+ }
+ }
+}
+
Ah, much better. Nodes also can take other parameters to filter the +returned content. Let's try the "name" filter which restricts our +search to people named Lydia:
+{
+ people(first: 3, name: "Lydia") {
+ edges {
+ node {
+ name
+ }
+ }
+ }
+}
+
Results in:
+{
+ "data": {
+ "people": {
+ "edges": [
+ {
+ "node": {
+ "name": "Lydia Brasch"
+ }
+ },
+ {
+ "node": {
+ "name": "Lydia Graves Chassaniol"
+ }
+ },
+ {
+ "node": {
+ "name": "Lydia C. Blume"
+ }
+ }
+ ]
+ }
+ }
+}
+
It is also possible to request data from multiple root nodes at once, +for example:
+{
+ people(first: 1) {
+ edges {
+ node { name }
+ }
+ }
+ bills(first: 1) {
+ edges {
+ node { title }
+ }
+ }
+}
+
Would give back something like:
+{
+ "data": {
+ "people": {
+ "edges": [
+ {
+ "node": {
+ "name": "Lydia Brasch"
+ }
+ }
+ ]
+ },
+ "bills": {
+ "edges": [
+ {
+ "node": {
+ "title": "Criminal Law - Animal Abuse Emergency Compensation Fund - Establishment"
+ }
+ }
+ ]
+ }
+ }
+}
+
You may notice something here, that you get back just the data you need. +This is extremely powerful, and lets you do the equivalent of many +traditional API calls in a single query.
+Let's take a look at a more useful example:
+{
+ bill(jurisdiction: "New York", session: "2017-2018", identifier: "S 5772") {
+ title
+ actions {
+ description
+ date
+ }
+ votes {
+ edges {
+ node {
+ counts {
+ value
+ option
+ }
+ votes {
+ voterName
+ voter {
+ id
+ contactDetails {
+ value
+ note
+ type
+ }
+ }
+ option
+ }
+ }
+ }
+ }
+ sources {
+ url
+ }
+ createdAt
+ updatedAt
+ }
+}
+
There's a lot going on there, let's break it down:
+bill(jurisdiction: "New York", session: "2017-2018", identifier: "S 5772") {
+
We're hitting the bill
root node, which takes 3 parameters. This
+should get us to a single bill from New York.
title
+
This is going to give us the title, just like we saw before.
+actions {
+ description
+ date
+}
+
Here we're going into a child node, in this case all of the actions +taken on the bill. For each action we're requesting a the date & +description.
+votes {
+ edges {
+ node {
+
Here too we're going into a child node, but note that this time we use +that "edges" and "node" pattern that we see on root level nodes. +Certain child nodes in the API have the ability to be paginated or +further limited, and votes happen to be one of them. In this case +however we're not making use of that so we'll just ignore this.
+(A full discussion of this pattern is out of scope but check out the +Relay pagination specification for more +detail for +more.)
+counts {
+ value
+ option
+}
+votes {
+ voterName
+ voter {
+ id
+ contactDetails {
+ value
+ note
+ type
+ }
+ }
+ option
+}
+}
+
Here we grab a few more fields, including child nodes of each vote on +our Bill.
+First, we get a list of counts (essentially pairs of outcomes + numbers +e.g. (yes, 31), (no, 5))
+We also get individual legislator votes by name, and we traverse into +another object to get the Open States ID and contact details for the +voter. (Don't sweat the exact data model here, there will be more on +the structure once we get to the actual graph documentation.)
+sources {
+ url
+}
+createdAt
+updatedAt
+
And back up at the top level, we grab a few more pieces of information +about the Bill.
+And now you've seen a glimpse of the power of this API. We were able to +get back theexact fields we wanted on a bill, contact information on the +legislators that have voted on the bill, and more.
+Our result looks like this:
+{
+ "data": {
+ "bill": {
+ "title": "Relates to bureaus of administrative adjudication",
+ "actions": [
+ {
+ "description": "REFERRED TO LOCAL GOVERNMENT",
+ "date": "2017-04-28"
+ },
+ {
+ "description": "COMMITTEE DISCHARGED AND COMMITTED TO RULES",
+ "date": "2017-06-19"
+ },
+ {
+ "description": "ORDERED TO THIRD READING CAL.1896",
+ "date": "2017-06-19"
+ },
+ {
+ "description": "RECOMMITTED TO RULES",
+ "date": "2017-06-21"
+ }
+ ],
+ "votes": {
+ "edges": [
+ {
+ "node": {
+ "counts": [
+ {
+ "value": 25,
+ "option": "yes"
+ },
+ {
+ "value": 0,
+ "option": "no"
+ },
+ {
+ "value": 0,
+ "option": "other"
+ }
+ ],
+ "votes": [
+ {
+ "voterName": "John J. Bonacic",
+ "voter": {
+ "id": "ocd-person/da013cd5-dc67-4e65-a310-73aa32ad1f7c"
+ "contactDetails": [
+ {
+ "value": "bonacic@nysenate.gov",
+ "note": "Capitol Office",
+ "type": "email"
+ },
+ {
+ "value": "Room 503\nAlbany, NY 12247",
+ "note": "District Office",
+ "type": "address"
+ },
+ {
+ "value": "518-455-3181",
+ "note": "District Office",
+ "type": "voice"
+ },
+ ...etc...
+ ]
+ },
+ "option": "yes"
+ },
+ {
+ "voterName": "Neil D. Breslin",
+ "voter": {
+ "id": "ocd-person/4b710aee-1b99-42e0-90e2-d41338e8c5df"
+ "contactDetails": [ ...etc... ],
+ },
+ "option": "yes"
+ },
+ {
+ "voterName": "David Carlucci",
+ "voter": {
+ "id": "ocd-person/1b0feab9-02a7-4bcc-b089-3ab23286da68"
+ "contactDetails": [ ...etc... ],
+ },
+ "option": "yes"
+ },
+ ]
+ }
+ },
+ ...etc...
+ ]
+ },
+ "sources": [
+ {
+ "url": "http://legislation.nysenate.gov/api/3/bills/2017-2018/S5772?summary=&detail="
+ },
+ {
+ "url": "http://www.nysenate.gov/legislation/bills/2017/S5772"
+ },
+ {
+ "url": "http://assembly.state.ny.us/leg/?default_fld=&bn=S5772&Summary=Y&Actions=Y&Text=Y"
+ }
+ ],
+ "createdAt": "2017-07-15 05:08:15.848526+00:00",
+ "updatedAt": "2017-07-15 05:08:15.848541+00:00"
+ }
+ }
+}
+
There are a few other things to be aware of while using the API:
+GraphQL is still quite new, so we figured it might be good to provide +some helpful tips on how to think about the data and how you'll use the +API.
+First, it is probably well worth your time to play around in GraphiQL to +explore the API and data. It was heavily used when developing the API +and writing tests, and is a very powerful tool, particularly when you +make use of the self-documenting nature of the graph.
+When you're thinking about how to query don't necessarily try to
+replicate your old API calls exactly. For example, perhaps you were
+grabbing all bills that met a given criteria and then grabbing all
+sponsors contact details. This can now be done in one call by traversing
+from the bills-root
root node into the BillSponsorshipNode
and then up to the
+PersonNode
and finally to the ContactDetailNode
This may sound
+complex at first, but once you get the hang of it, it really does unlock
+a ton of power and will make your apps more powerful and efficient.
In several places (such as the bills-root
and BillNode
's votes
) we mention that nodes are paginated.
What this means in practice is that instead of getting back the
+underlying node type, say BillNode
, directly, you'll get back
+BillConnectionNode
or similar. (In practice there are connection node
+types for each paginated type, but all work the same way in our case.)
Each paginated endpoint accepts any of four parameters:
+first
- given an integer N, only return the first N nodeslast
- given an integer N, only return the last N nodesafter
- combined with first
, will return first N nodes after a
+ given "cursor"before
- combined with last
, will return last N nodes before a
+ given "cursor"So typically you'd paginate using first
, obtaining a cursor, and then
+calling the API again with a combination of first
and after
.
The same process could be carried out with last
and before
to
+paginate in reverse.
Let's take a look at everything that pagination makes available:
+{
+ bills(first:20) {
+ edges {
+ node {
+ title
+ }
+ cursor
+ }
+ pageInfo {
+ hasNextPage
+ hasPreviousPage
+ endCursor
+ startCursor
+ }
+ totalCount
+ }
+}
+
You'll see that the connection node has three nodes: edges
,
+pageInfo
, and totalCount
edges
- a list of objects that each have a node
and cursor
attribute:node
- the underlying node type, in our case BillNode
cursor
- an opaque cursor for this particular item, it can
+ be used with the before
and after
parameters each
+ paginated node accepts as arguments.pageInfo
- a list of helpful pieces of information about this page:hasNextPage
- boolean that is true if there is another
+ page after thishasPreviousPage
- boolean that is true if there is a page
+ before thisendCursor
- last cursor in the set of edges, can be used
+ with after
to paginate forwardstartCursor
- first cursor in the set of edges, can be
+ used with before
to paginate backwardstotalCount
- total number of objects available from this
+ connection
Let's say you want to get all of the people matching a given criteria:
+You'd start with a query for all people matching your criteria, +ensuring to set the page size to no greater than the maximum:
+{
+ people(memberOf: "Some Organization", first: 100) {
+ edges {
+ node {
+ name
+ }
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+}
+
Let's say we got back a list of 100 edges and our pageInfo
object
+looked like:
{
+ "hasNextPage": true,
+ "endCursor": "ZXJyYXlxb20uZWN0aW9uOjA="
+}
+
So you'd make another call:
+{
+ people(memberOf: "Some Organization", first: 100, after:"ZXJyYXlxb20uZWN0aW9uOjA=" ) {
+ edges {
+ node {
+ name
+ }
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+}
+
And let's say in this case you got back only 75 edges, and our
+pageInfo
object looks like:
{
+ "hasNextPage": false,
+ "endCursor": "AXjYylxX2bu1wxa9uunnb="
+}
+
We'd stop iteration at this point, of course, if hasNextPage had been +true, we'd continue on until it wasn't.
+A really useful trick that is often overlooked is that you can rename +fields when retrieving them, for example:
+{
+ republicans: people(memberOf: "Republican", first: 5) {
+ edges {
+ node {
+ full_name: name
+ }
+ }
+ }
+}
+
Would give back:
+{
+ "data": {
+ "republicans": {
+ "edges": [
+ {
+ "node": {
+ "full_name": "Michelle Udall"
+ }
+ },
+ {
+ "node": {
+ "full_name": "Kimberly Yee"
+ }
+ },
+ {
+ "node": {
+ "full_name": "Regina E. Cobb"
+ }
+ },
+ {
+ "node": {
+ "full_name": "Michelle B. Ugenti-Rita"
+ }
+ },
+ {
+ "node": {
+ "full_name": "David Livingston"
+ }
+ }
+ ]
+ }
+ }
+}
+
Note that we're both renaming a top-level node here as well as a piece +of data within the query.
+You can also use this to query the same root node twice (doing so +without renaming isn't allowed since it results in a name conflict).
+For example:
+{
+ republicans: people(memberOf: "Republican", first: 5) {
+ edges {
+ node {
+ full_name: name
+ }
+ }
+ }
+ democrats: people(memberOf: "Democratic", first: 5) {
+ edges {
+ node {
+ full_name: name
+ }
+ }
+ }
+}
+
Unless otherwise noted (most notably createdAt
and updatedAt
all
+date objects are "fuzzy". Instead of being expressed as an exact date,
+it is possible a given date takes any of the following formats:
Action/Vote times are all assumed to be in the state capitol's time +zone.
+Times related to our updates such as updatedAt and createdAt are in UTC.
+In several places such as bill sponsorships and votes you'll notice
+that we have a raw string representing a person or organization as well
+as a place for a link to the appropriate OrganizationNode
or PersonNode
.
Because of the way we collect the data from states, we always collect +the raw data and later make an attempt to (via a mix of automated +matching and manual fixes) connect the reference with data we've +already collected.
+In many cases these linkages will not be provided, but with some +upcoming new tools to help us improve this matching we'll be able to +dramatically improve the number of matched entities in the near future.
+ + + + + + +As seen in the introduction, when constructing a query you will start +your query at one (or more) root nodes. The following root nodes are +available:
+Get a list of all jurisdictions.
+This will return a list of JurisdictionNode
objects, one for each state (plus Puerto Rico and DC).
Pagination: This endpoint accepts the usual
+pagination
parameters, but pagination is
+not required.
Get a list of all people matching certain criteria.
+This will return a list of PersonNode
objects, one for each person matching your query.
Pagination: This endpoint accepts the usual pagination
parameters, and you must
+limit your results to no more than 100 using either the "first" or "last" parameter.
name
Limit response to people who's name contains the provided string.
+Includes partial matches & case-insensitive matches.
+memberOf
Limit response to people that have a currently active membership +record for an organization. The value passed to memberOf can be an +ocd-organization ID or a name (e.g. 'Republican' or 'Nebraska Legislature').
+everMemberOf
Limit response to people that have any recorded membership record +for an organization. Operates as a superset of memberOf.
+Specifying memberOf
and everMemberOf
in the same query is
+invalid.
district
When specifying either memberOf or everMemberOf, limits to people +who's membership represented the district with a given label. (e.g. +memberOf: "Nebraska Legislature", district: "7")
+Specifying district
without memberOf
or everMemberOf
is
+invalid.
latitude
and longitude
Limit to people that are currently representing the district(s) +containing the point specified by the provided coordinates.
+Must be specified together.
+Get a list of all bills matching certain criteria.
+This will return a list of BillNode
+objects, one for each person matching your query.
Pagination: This endpoint accepts the usual
+pagination
parameters, and you must limit your results to no more than 100 using either the "first" or "last" parameter.
jurisdiction
Limit to bills associated with given jurisdiction, parameter can +either be a human-readable jurisdiction name or an ocd-jurisdiction +ID.
+chamber
Limit to bills originating in a given chamber. (e.g. upper, lower, +legislature)
+session
Limit to bills originating in a given legislative session. This
+parameter should be the desired session's identifier
. (See
+LegislativeSessionNode
).
classification
Limit to bills with a given classification (e.g. "bill" or +"resolution")
+subject
Limit to bills with a given subject (e.g. "Agriculture")
+searchQuery
Limit to bills that contain a given term. (Experimental until 2020!)
+updatedSince
Limit to bills that have had data updated since a given time (UTC).
+Time should be in the format YYYY-MM-DD[THH:MM:SS].
+actionsSince
Limit to bills that have had actions since a given time (UTC).
+Time should be in the format YYYY-MM-DD.
+Look up a single jurisdiction by name or ID.
+This will return a single JurisdictionNode
object with the provided name or ID parameter.
name
The human-readable name of the jurisdiction, such as 'New Hampshire'.
+id
The ocd-jurisdiction ID of the desired jurisdiction, such as +'ocd-jurisdiction/country:us/state:nh'.
+You are required to provide one of the two available parameters.
+Look up a single person by ocd-person ID.
+This will return a single PersonNode
by ID.
id
ocd-person ID for the desired individual.
+Look up a single organization by ocd-organization ID.
+This will return a single OrganizationNode
by ID.
id
ocd-organization ID for the desired individual.
+Look up a single bill by ID, URL, or (jurisdiction, session, identifier) +combo.
+This will return a single BillNode
object with the specified bill.
id
The ocd-bill ID of the desired bill, such as +'ocd-jurisdiction/country:us/state:nh'.
+openstatesUrl
The URL of the desired bill, such as +'https://openstates.org/nc/bills/2019/HB760/'.
+jurisdiction
, session
, identifier
Must be specified together to fully identify a bill.
+As is true elsewhere, jurisdiction may be specified by name (New +Hampshire) or ocd-jurisdiction ID +(ocd-jurisdiction/country:us/state:nh).
+Session is specified by legislative session identifier (e.g. 2018 or +49).
+Identifier is the exact identifier of the desired bill, such as "HB 327".
+You are required to provide one either id
or the other parameters to
+fully specify a bill. Use bills
if you are looking for something more
+broad.
Starting at the base nodes, data in the API is represented as +interconnected nodes of various types. This page provides an overview of +the nodes.
+Another good way to get acquainted with the layout is to use the +GraphiQL browser (click Docs in the +upper right corner).
+A Jurisdiction is the Open Civic Data term +for the top level divisions of the US. Open States is comprised of 52 +jurisdictions, one for each state, and two more for D.C. and Puerto +Rico.
+Each JurisdictionNode has the following attributes & nodes available:
+id
- ocd-jurisdiction identifier, these are permanent identifiers
+ assigned to each Jurisdiction
name
- human-readable name for the jurisdiction (e.g. Kansas)
url
- URL of official website for jurisdiction
featureFlags
- reserved for future use
legislativeSessions
- Paginated list (see pagination
) of
+ LegislativeSessionNode belonging to this
+ jurisdiction's legislature.
organizations
- Paginated list of OrganizationNode belonging to this jurisdiction.classification
parameterlastScrapedAt
- Time when last scrape finished.
See also: Open Civic Data Jurisdiction +reference
+A legislative session is a convening of the legislature, either a +primary or special session.
+Each LegislativeSessionNode has the following attributes and nodes +available:
+jurisdiction
- JurisdictionNode which this
+ session belongs to.identifier
- short identifier by which this session is referred to
+ (e.g. 2017s1 or 121)name
- formal name of session (e.g. "2017 Special Session #1"
+ or "121st Session"classification
- "primary" or "special"startDate
- start date of session if knownendDate
- end date of session if knownDivisions represent particular geopolitical boundaries. Divisions exist +for states as well as their component districts and are tied closely to +political geographies.
+id
- Open Civic Data Division
+ IDname
- human-readable name for the divisionredirect
- link to another DivisionNode, only present if division
+ has been replacedcountry
- country code (will be "us") for all Open States
+ divisionscreatedAt
- date at which this object was created in our systemupdatedAt
- date at which this object was last updated in our
+ systemextras
- JSON string with optional additional information about
+ the objectPeople, typically legislators and their associated metadata.
+Note that most fields are optional beyond name as often we don't have a +reliable given/family name or birthDate for instance.
+name
- primary name for the person
sortName
- alternate name to sort by (if known)
familyName
- hereditary name, essentially a "last name" (if
+ known)
givenName
- essentially a "first name" (if known)
image
- full URL to official image of legislator
birthDate
- see date-format
deathDate
- see date-format
identifiers
- list of other known identifiers,
+ IdentifierNode
otherNames
- list of other known names, NameNode
links
- official URLs relating to this person,
+ LinkNode
contactDetails
- ways to contact this person (via email, phone,
+ etc.), contactdetailnode
currentMemberships
- currently active memberships MembershipNodeclassification
parameter to only
+ get memberships to certain types of
+ OrganizationNodeoldMemberships
- inactive memberships MembershipNodeclassification
parameter to only
+ get memberships to certain types of
+ OrganizationNodesources
- URLs which were used in compiling Open States' information on this subject, [LinkNode]
createdAt
- date at which this object was created in our system
updatedAt
- date at which this object was last updated in our
+ system
extras
- JSON string with optional additional information about
+ the object
See also:
+ +Organizations that comprise the state legislatures and their associated +metdata.
+A typical bicameral legislature is comprised of a top-level organization +(classification=legislature), two chambers (classification=upper & +lower), and any number of committees (classification=committee).
+Each Organization is comprised of the following attributes and nodes:
+name
- primary name for the person
image
- full URL to official image for organization
classification
- the type of organization as described above
foundingDate
- see date-format
dissolutionDate
- see date-format
parent
- parent OrganizationNode if one exists
children
- paginated list of child OrganizationNode objectsclassification
parametercurrentMemberships
- list of all current members of this
+ Organization
identifiers
- list of other known identifiers for this
+ organization, IdentifierNode
otherNames
- list of other known names for this organization,
+ NameNode
links
- official URLs relating to this person,
+ LinkNode
sources
- URLs which were used in compiling Open States'
+ information on this subject, [LinkNode]
createdAt
- date at which this object was created in our system
updatedAt
- date at which this object was last updated in our
+ system
extras
- JSON string with optional additional information about
+ the object
See also:
+ +A MembershipNode represents a connection between a +personnode and a organizationnode. A +membership may optionally also reference a particular +postnode, such as a particular seat within a given chamber.
+Each membership has the following attributes and nodes:
+id
- Open Civic Data Membership
+ IDpersonName
the raw name of the person that the membership
+ describes (see name-matching
person
- personnodeorganization
- organizationnodepost
- postnodelabel
- label assigned to this membershiprole
- role fulfilled by this membershipstartDate
- start date of membership if knownendDate
- end date of membership if knowncreatedAt
- date at which this object was created in our systemupdatedAt
- date at which this object was last updated in our
+ systemextras
- JSON string with optional additional information about
+ the objectSee also:
+ +A PostNode represents a given position within an organization. The most +common example would be a seat such as Maryland's 4th House Seat.
+It is worth noting that some seats can have multiple active memberships
+at once, as noted in maximumMemberships
.
Each post has the following attributes and nodes:
+id
- Open Civic Data Post
+ IDlabel
- label assigned to this post (e.g. 3)role
- role fulfilled by this membership (e.g. 'member')division
- related divisionnode if this role has
+ a relevant divisionstartDate
- start date of membership if knownendDate
- end date of membership if knownmaximumMemberships
- typically 1, but set higher in the case of
+ multi-member districtscreatedAt
- date at which this object was created in our systemupdatedAt
- date at which this object was last updated in our
+ systemextras
- JSON string with optional additional information about
+ the objectSee also:
+ +A BillNode represents any legislative instrument such as a bill or +resolution.
+Each node has the following attributes and nodes available:
+id
- Internal ocd-bill identifier for this bill.legislativeSession
- link to
+ LegislativeSessionNode this bill is fromidentifier
- primary identifier for this bill (e.g. HB 264)title
- primary title for this billfromOrganization
- organization (typically upper or lower chamber)
+ primarily associated with this billclassification
- list of one or more bill types such as "bill"
+ or "resolution"subject
- list of zero or more subjects assigned by the stateabstracts
- list of abstracts provided by the state,
+ BillAbstractNodeotherTitles
- list of other titles provided by the state,
+ BillTitleNodeotherIdentifiers
- list of other identifiers provided by the
+ state, BillIdentifierNodeactions
- list of actions (such as introduction, amendment,
+ passage, etc.) that have been taken on the bill,
+ BillActionNodesponsorships
- list of bill sponsors,
+ BillSponsorshipNoderelatedBills
- list of related bills as provided by the state,
+ RelatedBillNodeversions
- list of bill versions as provided by the state,
+ BillDocumentNodedocuments
- list of related documents (e.g. legal analysis, fiscal
+ notes, etc.) as provided by the state,
+ BillDocumentNodevotes
- paginated list of VoteEventNode related
+ to the billsources
- URLs which were used in compiling Open States'
+ information on this subject, linknodeopenstatesUrl
- URL to bill page on OpenStates.orgcreatedAt
- date at which this object was created in our systemupdatedAt
- date at which this object was last updated in our
+ systemextras
- JSON string with optional additional information about
+ the objectRepresents an official abstract for a bill, each BillAbstractNode has +the following attributes:
+abstract
- the abstract itselfnote
- optional note about origin/purpose of abstractdate
- optional date associated with abstractRepresents an alternate title for a bill, each BillTitleNode has the +following attributes:
+title
- the alternate titlenote
- optional note about origin/purpose of this titleRepresents an alternate identifier for a bill, each BillIdentifierNode +has the following attributes:
+identifier
- the alternate identifierscheme
- a name for the identifier schemenote
- optional note about origin/purpose of this identifierRepresents an action taken on a bill, each BillActionNode has the +following attributes and nodes:
+organization
- OrganizationNode where this
+ action originated, will typically be either upper or lower chamber,
+ or perhaps legislature as a whole.description
- text describing the action as provided by the
+ jurisdiction.date
- date action took place (see date-format
)classification
- list of zero or more normalized action types (see
+ action-categorization
)order
- integer by which actions can be sorted, not intended for
+ display purposesextras
- JSON string providing extra information about this actionvote
- if there is a known associated vote, pointer to the
+ relevant VoteEventNoderelatedEntities
- a list of
+ RelatedEntityNode with known entities
+ referenced in this actionRepresents an entity that is related to a +BillActionNode.
+name
- raw (source-provided) name of entityentityType
- either organization or personorganization
- if entityType
is 'organization', the resolved
+ OrganizationNodeperson
- if entityType
is 'person', the resolved
+ PersonNodeSee name-matching
for details on how name
relates to organiation
and person
.
Represents a sponsor of a bill.
+name
- raw (source-provided) name of sponsoring person or
+ organizationentityType
- either organization or personorganization
- if entityType
is 'organization', the resolved
+ OrganizationNodeperson
- if entityType
is 'person', the resolved
+ PersonNodeprimary
- boolean, true if sponsorship is considered by the
+ jurisdiction to be "primary" (note: in many states multiple
+ primary sponsors may exist)classification
- jurisdiction-provided type of sponsorship, such
+ as "author" or "cosponsor". These meanings typically vary across
+ states, which is why we provide primary
as a sort of indicator of
+ the degree of sponsorship indicated.See name-matching
for details on how name
relates to organiation
and person
.
Represents relationships between bills.
+identifier
- identifier of related bill (e.g. SB 401)legislativeSession
- identifier of related session (in same jurisdiction)relationType
- type of relationship such as "companion", "prior-session", "replaced-by", or "replaces"relatedBill
- if the related bill is found to exist in our data, link to the BillNodeRepresentation of documents
and versions
on bills. A given document
+can have multiple links representing different manifestations (e.g.
+HTML, PDF, DOC) of the same content.
note
- note describing the purpose of the document or version
+ (e.g. Final Printing)date
- optional date associated with the documentlinks
- list of one or more MimetypeLinkNode
with actual URLs to
+ bills.Represents a single manifestation of a particular document.
+mediaType
- media type (aka MIME type) such as application/pdf or
+ text/htmlurl
- URL to official copy of the billtext
- text describing this particular manifestation (e.g. PDF)Represents a vote taken on a bill.
+id
- Internal ocd-vote identifier for this bill.identifier
- Identifier used by jurisdiction to uniquely identify
+ the vote.motionText
- Text of the motion being voted upon, such as "motion
+ to pass the bill as amended."motionClassification
- List with zero or more classifications for
+ this motion, such as "passage" or "veto-override"startDate
- Date on which the vote took place. (see
+ date-format
result
- Outcome of the vote, 'pass' or 'fail'.organization
- Related OrganizationNode where
+ vote took place.billAction
- Optional linked BillActionNode.votes
- List of PersonVoteNode for each
+ individual's recorded vote. (May not be present depending on
+ jurisdiction.)counts
- List of VoteCountNode with sums of each
+ outcome (e.g. yea/nay/abstain).sources
- URLs which were used in compiling Open States'
+ information on this subject, [LinkNode]createdAt
- date at which this object was created in our systemupdatedAt
- date at which this object was last updated in our
+ systemextras
- JSON string with optional additional information about
+ the objectSee also: Open Civic Data vote +format.
+Represents an individual person's vote (e.g. yea or nay) on a given +bill.
+option
- Option chosen by this individual. (yea, nay, abstain,
+ other, etc.)voterName
- Raw name of voter as provided by jurisdiction.voter
- Resolved PersonNode representing voter.
+ (See name-matching
note
- Note attached to this vote, sometimes used for explaining
+ an "other" vote.Represents the sum of votes for a given option
.
option
- Option in question. (yea, nay, abstain, other, etc.)value
- Number of individuals voting this way.Represents an alternate identifier, each with the following attributes:
+identifier
- the alternate identifierscheme
- a name for the identifier schemeRepresents an alterante name, each with the following attributes:
+name
- the alternate namenote
- note about usage/origin of this alternate namestartDate
- date at which this name began being valid (blank if
+ unknown)endDate
- date at which this name stopped being valid (blank if
+ unknown or still active)Represents a single link associated with a person or used as a source.
+url
- URLtext
- text describing the use of this particular URLUsed to represent a contact method for a given person.
+type
- type of contact detail (e.g. voice, email, address, etc.)value
- actual phone number, email address, etc.note
- used to group contact data by location (e.g. Home Address,
+ Office Address)label
- human-readable label for this contact detailOpen States provides a JSON API that can be used to programatically +access state legislative information.
+The root URL for the API is https://v3.openstates.org/.
+API keys are required. You can register for an API
+key and once activated,
+you\'ll pass your API key via the X-API-KEY
header or ?apikey
query
+parameter.
Auto-generated interactive documentation is available at either:
++++
+- https://v3.openstates.org/docs/
+- https://v3.openstates.org/redoc/ (whichever you prefer)
+
Issues should be filed at our issue +tracker.
+You can also check out our introductory blog +post for more +details.
+Method | +Description | +Interactive Docs | +
---|---|---|
/jurisdictions | +Get list of available jurisdictions. | +try it! | +
/jurisdictions/{jurisdiction_id} | +Get detailed metadata for a particular jurisdiction. | +try it! | +
/people | +List or search people (legislators, governors, etc.) | +try it! | +
/people.geo | +Get legislators for a given location. | +try it! | +
/bills | +Search bills by various criteria. | +try it! | +
/bills/ocd-bill/{uuid} | +Get bill by internal ID. | +try it! | +
/bills/{jurisdiction}/{session}/{id} | +Get bill by jurisdiction, session, and ID. | +try it! | +
/committees | +Get list of committees by jurisdiction. | +try it! | +
/committees/{committee_id} | +Get details on committee by internal ID. | +try it! | +
/events | +Get list of events by jurisdiction. | +try it! | +
/events/{event_id} | +Get details on event by internal ID. | +try it! | +
The fundamental unit by which data is partitioned is the +\'jurisdiction.\' If you are just interested in states you can +consider the words synonymous for the most part. Jurisdictions +include states, DC & Puerto Rico, and municipal governments for +which we have limited support.
+A legislator, governor, mayor, etc.
+Each person possibly has a number of roles, at most one of which is +considered \'current.\'
+A proposed piece of legislation, encompasses bills, resolutions, +constitutional amendments, etc.
+A given bill may have any number of votes, sponsorships, actions, +etc.
+\n {translation(\"search.result.term.missing\")}: {...missing}\n
\n }\n