Other Notes

There are a few other things to be aware of while using the API:

Explore the Graph

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 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.

Renaming fields

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
      }
    }
  }
}

Fuzzy Date Format

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:

  • YYYY
  • YYYY-MM
  • YYYY-MM-DD
  • YYYY-MM-DD HH:MM:SS (if times are allowed)

Name Matching

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.