GoCodebook Search API
The Search API from GoCodebook — 1 operation(s) for search.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/gocodebook-com:gocodebook-com-search-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: GoCodebook Search API
version: 1.0.0
description: 'Search California local ordinances (city and county codes) and, with an API key, California state law, Title 24 building codes and federal law, and get structured results with verbatim excerpts, citations and links.
**Free sample** — no key, rate-limited per address, local ordinances only, no AI overview.
**Paid access** — send an API key (`Authorization: Bearer gcb_live_…`). Adds the `subnational` layer (California statutes, regulations, rent control, state guidance and Title 24 building codes, as excerpts) and the `national` layer (federal statutes and regulations, HUD guidance) through `filters.layers`. $0.30 a search with the AI overview included, drawn from a prepaid balance; a search with no results is not charged. `gcb_test_…` keys are free and rate-limited. Pricing, keys and limits: https://gocodebook.com/developers
Requests, including query text, are stored. Results are code text, not legal advice.'
servers:
- url: https://gocodebook.com/api
- url: https://api.gocodebook.com
description: Dedicated API host (same API).
security:
- {}
- apiKey: []
tags:
- name: Search
paths:
/v1/search:
post:
summary: Search local ordinances (and state and federal law with a key)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
maxLength: 300
jurisdiction:
type: string
description: 'A city or county id (us-ca-san-jose), or us-ca for every California city and county. Omitted: the place the query names, else every California city and county.'
filters:
type: object
properties:
layers:
type: array
items:
type: string
enum:
- local
- subnational
- national
description: Default `["local"]`. `subnational` (alias `state`) and `national` (alias `federal`) need an API key; the free sample answers 400 layer_not_available. With more than one layer, each keeps at least `limit` ÷ layers results (at least 1) when it has matches.
as_of:
type: string
format: date
limit:
type: integer
minimum: 1
maximum: 10
default: 5
include:
type: array
items:
type: string
enum:
- overview
description: Paid access only. The free sample answers 403 overview_requires_paid_access.
excerpt_chars:
type: integer
minimum: 200
maximum: 1200
default: 1200
examples:
basic:
value:
query: maximum fence height in a front yard
jurisdiction: us-ca-san-jose
responses:
'200':
description: Search result
content:
application/json:
schema:
type: object
required:
- object
- request_id
- query
- results
- notices
- usage
properties:
object:
const: search_result
api_version:
type: string
request_id:
type: string
tier:
type: string
query:
type: object
properties:
text:
type: string
jurisdiction:
allOf:
- type: object
required:
- id
- name
- level
properties:
id:
type: string
examples:
- us-ca-san-jose
description: 'Public jurisdiction id: country-region-place.'
name:
type: string
level:
type: string
enum:
- national
- subnational
- county
- municipal
properties:
resolved_from:
type: string
enum:
- request
- query
- default
includes_all_local:
type: boolean
filters_applied:
type: object
results:
type: array
items:
type: object
required:
- id
- rank
- citation
- section
- document
- jurisdiction
- layer
- excerpt
- excerpt_truncated
- url
properties:
id:
type: string
description: Section id. In the free sample it may change when a code is re-collected.
rank:
type: integer
score:
type:
- number
- 'null'
description: Relative relevance within this response.
citation:
type: string
examples:
- San Jose Municipal Code § 20.80.175
section:
type: object
properties:
number:
type:
- string
- 'null'
heading:
type: string
path:
type: array
items:
type: string
document:
type: object
properties:
id:
type: string
title:
type: string
type:
type: string
enum:
- ordinance
- statute
- regulation
- building_code
- guidance
- case
edition:
type:
- string
- 'null'
jurisdiction:
type: object
required:
- id
- name
- level
properties:
id:
type: string
examples:
- us-ca-san-jose
description: 'Public jurisdiction id: country-region-place.'
name:
type: string
level:
type: string
enum:
- national
- subnational
- county
- municipal
layer:
type: string
enum:
- national
- subnational
- local
excerpt:
type: string
description: Plain text, at most excerpt_chars characters. Never the whole section.
excerpt_truncated:
type: boolean
url:
type:
- string
- 'null'
description: The full section on gocodebook.com. Show it to your users.
notices:
type: array
items:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable code. New codes may be added; show `message` for a code you do not recognise.
examples:
- section_not_found
- section_elsewhere
- section_prefix
- zone_not_found
- zoning_not_held
- scope_mismatch
- corpus_gap
- as_of_gap
- address_query
- jurisdiction_needed
message:
type: string
data:
type: object
overview:
type: object
required:
- status
properties:
status:
type: string
enum:
- complete
- failed
- rate_limited
summary:
type: string
description: The bottom line, at most ~350 characters, with [n] markers.
why:
type:
- string
- 'null'
check_next:
type:
- string
- 'null'
text:
type: string
description: The whole overview as markdown.
citations:
type: array
items:
type: object
properties:
marker:
type: integer
citation:
type: string
url:
type:
- string
- 'null'
section_id:
type:
- string
- 'null'
result_id:
type:
- string
- 'null'
description: The matching entry in `results`, when it is there.
model:
type: string
disclaimer:
type: string
message:
type: string
description: Present only on paid requests that asked for it.
usage:
type: object
properties:
search:
type: integer
overview:
type: integer
units:
type: integer
description: Units charged for this request (keys only; 0 for test keys).
month_to_date_units:
type:
- integer
- 'null'
description: Live keys only.
cost_usd:
type: number
description: 'Prepaid live keys: what this request cost.'
balance_usd:
type:
- number
- 'null'
description: 'Prepaid live keys: the API balance after it.'
'400':
description: Invalid request
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'401':
description: Invalid or revoked API key
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'402':
description: Insufficient prepaid balance, or an invoiced account's monthly cap
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'403':
description: Needs paid access or a feature not enabled (e.g. the AI overview)
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'429':
description: Rate limited. See Retry-After.
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'503':
description: Temporarily unavailable. Nothing ran.
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
tags:
- Search
operationId: postV1Search
x-operation-id-source: derived
get:
summary: Search (query-string form)
parameters:
- name: query
in: query
required: true
schema:
type: string
- name: jurisdiction
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: include
in: query
schema:
type: string
enum:
- overview
- name: layers
in: query
schema:
type: string
- name: as_of
in: query
schema:
type: string
format: date
- name: excerpt_chars
in: query
schema:
type: integer
responses:
'200':
description: Same body as POST
'400':
description: Invalid request
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'401':
description: Invalid or revoked API key
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'402':
description: Insufficient prepaid balance, or an invoiced account's monthly cap
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'403':
description: Needs paid access or a feature not enabled (e.g. the AI overview)
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'429':
description: Rate limited. See Retry-After.
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
'503':
description: Temporarily unavailable. Nothing ran.
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication
- permission
- billing
- rate_limited
- not_found
- api_error
code:
type: string
message:
type: string
param:
type:
- string
- 'null'
docs:
type: string
request_id:
type: string
tags:
- Search
operationId: getV1Search
x-operation-id-source: derived
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: Optional. gcb_live_… or gcb_test_… keys, created by an organization owner or admin. Without a key, requests run on the free sample tier.