Skip to content

docs(gov): document law results with legal labels on /search/gov #1708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
erikengervall wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs(gov): document law results with legal labels on /search/gov #1708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fda341d
docs(gov): document legal labels on Government Index results
erikengervall Oct 22, 2026
8b99748
docs(gov): document law results with legal labels on /search/gov
erikengervall Oct 22, 2026
b354328
docs(gov): state updated_at is always present on law results
erikengervall Oct 22, 2026
91f9f75
docs(gov): updated_at is omitted for external web results in the law …
erikengervall Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api-reference/endpoint/gov-search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: "Search the Government Index"
openapi: "/api-reference/v2-openapi.json GET /search/gov"
---

Search primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications. Results come back in the standard `web` group, the same shape as a web result from [`/search`](/api-reference/endpoint/search).
Search primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications. Results come back in the standard `web` group, the same shape as a web result from [`/search`](/api-reference/endpoint/search). Send `sources: ["law"]` to get the same results in a `law` group with the index's legal labels: `jurisdiction`, `court`, `court_type`, `cites`, `cited_as`, and `updated_at`. See [Legal labels](/features/gov#legal-labels).

`POST` is available on the same path with the same fields as a JSON body. Unknown fields and invalid filter values are rejected with `400`, and the error says which value to fix.

Expand Down
84 changes: 82 additions & 2 deletions api-reference/v2-openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6702,11 +6702,27 @@
"type": "string",
"minLength": 1
}
},
{
"name": "sources",
"in": "query",
"required": false,
"description": "Result groups to return. `web` returns plain search results. `law` returns the same results with the index's legal labels: `jurisdiction`, `court`, `court_type`, `cites`, `cited_as` and `updated_at`. Repeat the parameter to return both.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": ["web", "law"]
},
"default": ["web"]
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Ranked Government Index results in the `web` group.",
"description": "Ranked Government Index results in each group `sources` names, `web` by default.",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -6815,6 +6831,16 @@
"type": "string",
"minLength": 1,
"description": "Keep only pages from one site, such as `irs.gov`."
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": ["web", "law"]
},
"minItems": 1,
"default": ["web"],
"description": "Result groups to return. `web` returns plain search results. `law` returns the same results with the index's legal labels: `jurisdiction`, `court`, `court_type`, `cites`, `cited_as` and `updated_at`."
}
}
},
Expand All @@ -6827,7 +6853,7 @@
},
"responses": {
"200": {
"description": "Ranked Government Index results in the `web` group.",
"description": "Ranked Government Index results in each group `sources` names, `web` by default.",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -13069,6 +13095,60 @@
}
}
}
},
"law": {
"type": "array",
"description": "Present when `sources` includes `law`. The same results as `web`, in the same order, with the index's legal labels.",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"description": {
"type": "string",
"description": "Matched snippet from the source document."
},
"position": {
"type": "integer",
"description": "1-based rank in the result list."
},
"jurisdiction": {
"type": "string",
"description": "Jurisdiction label: `us` for federal, or `us-` plus a two-letter state or territory code. Absent when the index has no label."
},
"court": {
"type": "string",
"description": "CourtListener court id, such as `scotus` or `ca9`. Absent when the index has no label."
},
"court_type": {
"type": "string",
"description": "Type of court, one of the `courtType` filter values. Absent when the index has no label."
},
"cites": {
"type": "array",
"items": {
"type": "string"
},
"description": "Citation ids of the laws and cases the page cites. Absent when none are known."
},
"cited_as": {
"type": "array",
"items": {
"type": "string"
},
"description": "Citation ids other pages cite this page by. Pass one as `cites` to find the pages citing it. Absent when none are known."
},
"updated_at": {
"type": "integer",
"description": "When the page was crawled, in Unix milliseconds. Present for indexed pages, omitted for external web results."
}
}
}
}
}
}
Expand Down
49 changes: 49 additions & 0 deletions features/gov.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,55 @@ const result = await client.govSearch("qualified immunity", {

</CodeGroup>

### Legal labels

Add `sources: ["law"]` to get each result with the legal labels the index holds for the page, in a `law` group. `sources` defaults to `["web"]`; send `["web", "law"]` to get both groups, which list the same results in the same order.

<CodeGroup>

```bash cURL
curl -s -X POST "https://api.firecrawl.dev/v2/search/gov" \
-H "Content-Type: application/json" \
-d '{"query": "qualified immunity", "jurisdiction": "us", "sources": ["law"]}'
```

</CodeGroup>

Each `law` result has `url`, `title`, `description`, and `position`, like a `web` result, plus these fields. A label is absent when the index has no value for the page.

| Field | Value |
| --- | --- |
| `jurisdiction` | `us` for federal, or `us-` plus a two-letter state or territory code |
| `court` | CourtListener court id, such as `scotus` or `ca9` |
| `court_type` | one of the `courtType` filter values |
| `cites` | citation ids of the laws and cases the page cites |
| `cited_as` | citation ids other pages cite this page by |
| `updated_at` | when the page was crawled, in Unix milliseconds; present for indexed pages, omitted for external web results |

```json
{
"success": true,
"data": {
"law": [
{
"url": "https://supreme.justia.com/cases/federal/us/555/223/",
"title": "Pearson v. Callahan",
"description": "Qualified immunity balances two important interests...",
"position": 1,
"jurisdiction": "us",
"court": "scotus",
"court_type": "federal-supreme",
"cites": ["us:usc:42:1983"],
"cited_as": ["us:us:555:223"],
"updated_at": 1760000000000
}
]
}
}
```

To follow a citation, pass an id from `cites` or `cited_as` back as the `cites` filter: an id from `cited_as` finds the pages citing this one, and an id from `cites` finds other pages citing the same law or case.

The same search is also available on [`/search`](/features/search#gov-category-search) as `categories: ["gov"]`, with results in `data.web`. That category takes only the query; use `/search/gov` to filter.

<Note>
Expand Down
Loading