The LegiScan Pull API (https://api.legiscan.com): sessions, master bill lists, bills, bill text and full-text search for US states and Congress.

Auth: a free key from https://legiscan.com/legiscan. LegiScan takes it in the query string, so it is redacted from every error. Set legiscan.api-key or pass {api-key: ...} per call.

Queries: a public key has 30,000 queries a month, and every call here spends one, even when LegiScan answers from its cache.

Avoiding repeat pulls: compare each bill's change_hash from master-list-raw with the one you stored, and call bill only for those that changed. The package keeps no state: changed-bills takes your stored hashes, and hash-index builds the Map to store.

Errors: LegiScan answers HTTP 200 with status: "ERROR" for its own errors. Those are Errs carrying HttpError.

Context Vars

Optional
  • legiscan.api-key
  • legiscan.base-url

Functions

bill

fn (bill-id: Int): Map
fn (bill-id: Int, opts: Map): Map

getBill: one bill, with bill_number, title, description, state, status, session, progress, history, sponsors, votes, change_hash, and texts, whose rows carry the doc_id for bill-text.

bill-rows

fn (m: Any): Vec

The bill rows of a masterlist or searchresult Map, which LegiScan keys "0", "1", and so on beside other fields such as summary (pure).

bill-text

fn (doc-id: Int): Map
fn (doc-id: Int, opts: Map): Map

getBillText: one text document, with doc_id, bill_id, date, type, mime, text_size, text_hash, and bytes, the decoded document. mime says what the bytes are: PDF, HTML or Word. A document must fit in http.max-response-bytes (16 MiB by default) as base64.

Example

::lg ::legiscan
b ::lg/bill(1167968)
text ::lg/bill-text(first(b.texts).doc_id)
text.mime
text.bytes

call

fn (op: Str, params: Map, field: Str, opts: Map): Any

changed-bills

fn (rows: Vec, known: Map): Vec

The rows of a master list or search result whose change_hash differs from known, a Map of bill_id (as a string) to change_hash, including rows not in known (pure).

collect

fn (fetch: Fn, opts: Map, limit: Int): Vec

Follow pages of a search until limit rows or the last page. fetch takes opts (with page set) and returns one page. Each page spends one query.

Example

::lg ::legiscan
rows ::lg/collect((o) { ::lg/search-raw("money transmitter", o) }, {state: "CA"}, 5000)

collect-pages

fn (fetch: Fn, page-number: Int, limit: Int, acc: Vec): Any

decode-text

fn (text: Map): Map

A getBillText text Map with its base64 doc replaced by the decoded bytes (pure). An Err when doc isn't valid base64.

hash-index

fn (rows: Vec): Map

The Map of bill_id (as a string) to change_hash for rows, for the caller to store and pass to changed-bills next time (pure).

master-list

fn (session: Any): Vec
fn (session: Any, opts: Map): Vec

getMasterList: summary rows for every bill in a session, given a session_id, or a state abbreviation for its current session (which LegiScan says to use with caution). Each row has bill_id, number, change_hash, url, status, status_date, last_action, last_action_date, title, description.

master-list-for

fn (op: Str, session: Any, opts: Map): Any

master-list-raw

fn (session: Any): Vec
fn (session: Any, opts: Map): Vec

getMasterListRaw: bill_id, number and change_hash for every bill in a session, for spotting what changed.

Example

::lg ::legiscan
rows ::lg/master-list-raw(1791)
changed ::lg/changed-bills(rows, stored-hashes)
bills map(changed, (row) { ::lg/bill(row.bill_id) })
next-hashes ::lg/hash-index(rows)

next-page

fn (result: Any): Int?

The page after a search or search-raw result, from summary.page_current and summary.page_total, or null on the last page (pure).

fn (op: Str, query: Str, opts: Map): Any
fn (query: Str): Map
fn (query: Str, opts: Map): Map

getSearch: one page of 50 full-text results: {summary, results}. Each row has relevance, state, bill_number, bill_id, change_hash, url, text_url, last_action, last_action_date, title. opts: state (default "ALL"), id (a session), year, page, plus api-key.

Example

found ::legiscan/search("money transmitter", {state: "CA"})
found.summary.count
first(found.results).title

search-params

fn (query: Str, opts: Map): Map

Query parameters for a search (pure): query, plus id (a session) or state (default "ALL"), and year and page, from opts. year is 1 for all, 2 for current, 3 for recent, 4 for prior, or an exact year.

search-raw

fn (query: Str): Map
fn (query: Str, opts: Map): Map

getSearchRaw: one page of up to 2,000 results with only relevance, bill_id and change_hash, for keyword monitoring: {summary, results}. Takes the same opts as search.

search-result

fn (result: Any): Map

A searchresult as {summary, results} (pure). getSearch keys rows beside summary; getSearchRaw puts them under results.

session-list

fn (): Vec
fn (state: Str?): Vec
fn (state: Str?, opts: Map): Vec

getSessionList: the sessions for a state abbreviation, or for every state when state is null. Each has session_id, state_id, year_start, year_end, session_title, prior, sine_die, special and dataset_hash.

Example

sessions ::legiscan/session-list("CA")
first(sessions).session_id

session-params

fn (session: Any): Map

{id} for a session id, {state} for a state abbreviation; an Err for anything else (pure).