Skip to main content
POST /us/statutes/search ranks. It does not enumerate. Most of what follows depends on that difference, so settle it before you design a pipeline around search.

​
The ranking model

Search is hybrid. Two retrieval legs run in parallel over the same corpus:
  • a semantic leg, which matches on meaning, so a section can rank for a question that shares none of its wording
  • a keyword leg, which matches on the terms themselves
Their results are fused by reciprocal rank, then reranked by a cross-encoder that reads each candidate against your query. Sections carrying a dead actStatus are demoted rather than dropped, so a repealed provision can still appear, ranked below live law. See Status & Currency for how to filter those out entirely. A query shaped like a citation resolves directly to that section at rank 1. Passing 42 U.S.C. § 1983 as your query is a lookup.
If you already hold a well-formed citation, GET /us/statutes/resolve does the same job for fewer credits.

​
Query syntax needs matchType boolean

In the default mode (any), and in all and phrase, the query string is passed to retrieval as written. It is not parsed as an expression: So in any mode a query like defibrillator OR cardiac arrest runs as one semantic query over that whole string, including the word OR. When such a query looks like a Boolean expression, the response carries a queryHint saying so. To use operators, send matchType: "boolean". The query is then read as a terms-and-connectors expression (AND, OR, NOT, /s, /p, /N, wildcards, phrases and grouping), and every result satisfies it. See Boolean search.
In any mode, searching several concepts in one string dilutes the query and costs you recall on each of them. Issue one search per concept and union the returned actId values yourself, or write the concepts as one Boolean expression.

​
matchType

matchType is the exact-match control. all and phrase narrow results that ranking has already retrieved. Since they only narrow, an empty result under either means nothing we ranked for your query carried those terms. The corpus may still hold such a section, so fall back to any, or scope the query more tightly with the filters, before concluding something is missing. boolean is different: the expression is applied while the corpus is searched, not to a ranked pool afterwards, so a matching section is found wherever relevance would have ranked it, and it pages to the end of the matches (offset up to 10,000), where the other modes stop at 120 results. Best practices works through when each one earns its place.

​
What is indexed

Search reads the full canonical text of every section. Sections are split into overlapping passages, and each passage carries a header with its corpus, jurisdiction, status, hierarchy and section title. Headings and citations are therefore searchable, not just body text, and both retrieval legs see identical content. The excerpt on a result is one passage, sized by excerptChars. It is a ranking preview. For the authoritative text of a section, call GET /us/statutes/section/{actId}/body.

​
Filters are applied before retrieval

Every scoping filter (state, corpusType, code, titleNumber, chapter, part, actStatus, yearFrom / yearTo, changedSince, and the Federal Register filters) is compiled into the query itself rather than applied to the results afterwards. Two consequences follow:
  1. Narrowing does not cost depth. A search scoped to one state and one corpus type gets a full-depth pool within that slice, so scoping improves recall.
  2. Filters combine freely with paging, and every page of a query is cut from one ranking. See Pagination.
An unrecognised filter value, or an unrecognised filter name, returns 422 rather than silently widening your query.

​
When search is the wrong tool

Search returns the best matches for a query, up to a bounded number of them. If your requirement is every section in a body of law rather than the most relevant ones, browse the hierarchy instead: GET /us/statutes/divisions walks codes to chapters to sections and returns every section in a container with its actId.

Browse the hierarchy

Enumerate a bounded body of law without relying on ranking.
To size that body of law first, POST /us/statutes/count takes the same scoping filters, runs no ranking, and returns an exact section count. It accepts no query for the reason above: a count of “sections matching this query” would only ever be the size of the ranking window, not a fact about the corpus.

Boolean search

Terms and connectors with matchType boolean.

Pagination

How deep a result set goes, and how to page it.

Best practices

Scoping, matchType, and what to cache.

Status & currency

Filtering repealed and superseded law out of results.

Build a subject corpus

Enumerate, scope, hydrate, and keep it current.
Last modified on October 25, 2026