Skip to main content
A few habits make Vaquill integrations faster, cheaper, and more accurate. Follow these when you move from a prototype to production.

​
Scope every query

Pass corpusType (and state for state-scoped corpora) on POST /statutes/search. Scoping does two things: it sharpens relevance by removing off-target jurisdictions, and it makes your pages more predictable. An unscoped search ranks across the whole corpus, so a state-specific answer can be crowded out by federal or other-state matches.
Call GET /statutes/coverage first to learn what is queryable. Read a jurisdiction’s corpora keys and pass one back as corpusType. This avoids guessing a token that has no data for that state and wasting a call on an empty result.
Use GET /statutes/codes?state=XX to see the individual statutory codes (Penal, Civil, and so on) ingested for a state, and their section counts, when you want to explain a state’s structure to a user.

​
Cache coverage

Coverage grows weekly, not hourly. Cache the responses of /statutes/coverage, /statutes/states, and /statutes/codes for hours or a day rather than calling them on every request. They still count against your rate limits.

​
Store the actId values you care about

The actId (for example USC_T42_C21_S1983) is the stable handle for a section. Once a search surfaces a section your product depends on, store its actId and go straight to GET /statutes/section/{actId} or .../body on later runs. That skips the search entirely.

​
Retry on 429, handle 402

  • On 429, respect the Retry-After header and use exponential backoff. See Rate limits.
  • On 402, stop, surface a clear message, resolve it in your account dashboard, then retry.
  • Both are expected in production. Build for them rather than treating them as fatal.

​
Treat relevanceScore as a within-response rank

relevanceScore (0 to 1) orders results within a single response. It is a relative rank, not a calibrated confidence score. Do not compare scores across different queries and do not use a fixed threshold (for example “drop anything below 0.7”) to decide what to keep. To narrow results, tighten query, corpusType, and state instead. Each result carries source links (htmlUrl, pdfUrl, xmlUrl, textUrl, docxUrl, stateHtmlUrl, govInfoHtmlUrl, govInfoPdfUrl, externalUrl; any may be null). For user-facing deep links, prefer the official government link (state legislature or govinfo.gov) so readers land on authoritative text. This keeps your product grounded and verifiable.

Pagination

Page predictably with limit, offset, and hasMore.

Coverage

See the full jurisdiction and corpus matrix.