{"openapi":"3.1.0","info":{"title":"GovCrawl Search API","description":"\nA search engine covering official government websites in the United States,\nCanada, and the United Kingdom, from national departments down to city\ncouncils.\n\nEvery result comes from a domain verified as governmental, either because it\nappears in an official registry (CISA's `.gov` registry, the Cabinet Office's\n`.gov.uk` register, the Treasury Board's inventory of federal organizations) or\nbecause it sits in a namespace only a government can register in.\n\nSearches cover **all three countries by default**. Pass `country` to narrow\nthem.\n\n**The API is free and needs no key.** Please keep to a reasonable request rate.\n\n### Search operators\n\n| Operator | Example | Effect |\n|---|---|---|\n| `site:` | `site:irs.gov tax forms` | restrict to a domain |\n| `country:` | `country:ca passport` | restrict to a country |\n| `filetype:` | `budget filetype:pdf` | restrict by document type |\n| `level:` | `level:city parking permit` | restrict by level of government |\n| `state:` | `state:tx drivers license` | restrict by US state |\n| `intitle:` | `intitle:budget` | require a term in the title |\n| `inurl:` | `inurl:forms` | require a term in the URL |\n| `\"...\"` | `\"notice of proposed rulemaking\"` | exact phrase |\n| `-term` | `permits -parking` | exclude a term |\n","version":"1.0.0"},"paths":{"/api/v1/search":{"get":{"tags":["search"],"summary":"Search","description":"Search every indexed government page, in all countries unless narrowed.","operationId":"search_api_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":500,"description":"Search query","title":"Q"},"description":"Search query"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"1-indexed page number","default":1,"title":"Page"},"description":"1-indexed page number"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Results per page","default":10,"title":"Size"},"description":"Results per page"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Countries to search: us, ca, uk. Defaults to all of them.","title":"Country"},"description":"Countries to search: us, ca, uk. Defaults to all of them."},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by level of government: federal, state, county, city, tribal","title":"Level"},"description":"Filter by level of government: federal, state, county, city, tribal"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Two-letter state code","title":"State"},"description":"Two-letter state code"},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Restrict to domains","title":"Domain"},"description":"Restrict to domains"},{"name":"filetype","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"pdf, html, doc, docx","title":"Filetype"},"description":"pdf, html, doc, docx"},{"name":"facets","in":"query","required":false,"schema":{"type":"boolean","description":"Include aggregation counts","default":true,"title":"Facets"},"description":"Include aggregation counts"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/suggest":{"get":{"tags":["search"],"summary":"Suggest","description":"Autocomplete suggestions drawn from indexed page titles.","operationId":"suggest_api_v1_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"title":"Q"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/domains":{"get":{"tags":["metadata"],"summary":"Domains","description":"List the government domains in the index.","operationId":"domains_api_v1_domains_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"us, ca, uk","title":"Country"},"description":"us, ca, uk"},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by level of government","title":"Level"},"description":"Filter by level of government"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"title":"State"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Search"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/countries":{"get":{"tags":["metadata"],"summary":"Countries","description":"The countries in scope, with the levels of government each contributes.\n\nThe UI builds its country toggles from this, so adding a country to the\ncrawl does not need a matching change to the front end.","operationId":"countries_api_v1_countries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/stats":{"get":{"tags":["metadata"],"summary":"Stats","description":"Index and crawl coverage.\n\nServed from a value recomputed in the background, so the request never\nwaits on the frontier counts.","operationId":"stats_api_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["metadata"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}