Search APIs

Most of the Open Legislation data APIs include search functionality. We built our search layer using elasticsearch and we aim to provide as much elasticsearch functionality as possible through the APIs.

Every search layer API will have a required request parameter “term” and an optional request param “sort”.

term

The term parameter takes in an elasticsearch query string.

The simplest way to search is to send a general search term. For example, to search for legislation pertaining to apples, the following query will do the job:

GET /api/3/bills/search?term=apples

In addition to a simple search term, there are a number of advanced features available. Our search index is generated with data in the same JSON format as the API responses, so any response field that is nested under “result” is fair game for search. Going back to the previous example, a number of resolutions appear in the results for the apples search query. Looking back at the bill response, we see that resolutions are designated by the “resolution” boolean under “billType”. In order to filter resolutions out of the search results, a field query can be chained to the original query using “AND”:

GET /api/3/bills/search?term=apples%20AND%20billType.resolution:false

For a full enumeration of query features see the elasticsearch query string syntax.

sort

Searches can be sorted by any number of fields. This is accomplished using the sort request parameter, which takes a comma separated string of fields, each designated with a sort order (“ASC” or “DESC”) separated from the field with a colon.

Relevance. To sort by relevance, most relevant first, use sort=_score:DESC.

Text fields. To sort on a text field, use its .keyword subfield, for example sort=status.statusType.keyword:ASC.

For example, to get the 2013 governor’s program bills in canonical order:

GET /api/3/bills/2013/search?term=programInfo.name:Governor%20AND%20NOT%20_exists_:substitutedBy
                            &sort=programInfo.sequenceNo:ASC

Or, you may want to order them by their status and action date:

GET /api/3/bills/2013/search?term=programInfo.name:Governor%20AND%20NOT%20_exists_:substitutedBy
                            &sort=status.statusType.keyword:ASC,status.actionDate:DESC

Search Response

Search results are paged like other lists. See Paging.

{
  "success": true,
  "message": "",
  "responseType": "search-results list",
  "total": 7,
  "offsetStart": 1,
  "offsetEnd": 7,
  "limit": 10,
  "result": {
    "items": [
      {
        "result": { ... },            // A search result
        "rank": 13.046083,            // Relevance score, when sorted by relevance
        "highlights": {               // Matching text, by field, with matches wrapped in <em>
          "printNo": [ "<em>S11</em>" ]
        }
      },
      ...                           // More search results
    ],
    "size": 7
  }
}

highlights can be empty.