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
legiscan.api-keylegiscan.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).
run-search
fn (op: Str, query: Str, opts: Map): Any
search
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).