The local ordinance API for real estate software

Documentation

The full, interactive reference is at /developers/reference. The essentials:

Base URL

https://gocodebook.com/api/v1

JSON in, JSON out. Every response carries an x-request-id header and a request_id field — quote it when you write to us. The full contract is openapi.json (OpenAPI 3.1).

API keys

Without a key you are on the free sample. With paid access, an organization owner or admin creates keys on the team page (gocodebook.com/organization → API access) and sends one on every request:

curl -s https://api.gocodebook.com/v1/search \
  -H "Authorization: Bearer $GOCODEBOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "ADU rear setback", "jurisdiction": "us-ca-san-jose"}'

• gcb_test_… keys run real searches with small limits (10 a minute, 200 a day) and are never billed — use them while you integrate.
• gcb_live_… keys count usage in units: a search is 1 unit, and the AI overview comes with it at no extra cost. A search with no results is not counted.
• Prepaid. Live usage draws on your organization's API balance — $0.30 a search, AI overview included, unless your agreement says otherwise. Add funds by card on the team page; the card is saved so you can turn on auto-recharge ("when the balance is below $X, add $Y"). A request the balance cannot cover is refused with 402 insufficient_balance; nothing is ever billed afterwards.
• Every response with a key reports usage.units; live keys also get usage.cost_usd, usage.balance_usd and usage.month_to_date_units.
• The key is shown once, when it is created. Keep it on your server — never in browser or mobile app code. Revoke a key from the same page; it stops working immediately.

Search

POST /v1/search

curl -s https://gocodebook.com/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "maximum fence height in a front yard",
    "jurisdiction": "us-ca-san-jose",
    "limit": 3
  }'

The same search as a link, for a quick try in the browser:

curl -s "https://gocodebook.com/api/v1/search?query=short-term+rental+permit+santa+monica&limit=3"

Response

{
  "object": "search_result",
  "request_id": "req_…",
  "tier": "free",
  "query": {
    "text": "maximum fence height in a front yard",
    "jurisdiction": {
      "id": "us-ca-san-jose", "name": "San Jose", "level": "municipal",
      "resolved_from": "request", "includes_all_local": false
    },
    "filters_applied": { "layers": ["local"], "as_of": null }
  },
  "results": [
    {
      "id": "sec_…",
      "rank": 1,
      "score": 0.0328,
      "citation": "San Jose Municipal Code § …",
      "section": { "number": "…", "heading": "…", "path": ["Title 20", "…"] },
      "document": { "id": "san-jose", "title": "San Jose Municipal Code", "type": "ordinance", "edition": "2026-10" },
      "jurisdiction": { "id": "us-ca-san-jose", "name": "San Jose", "level": "municipal" },
      "layer": "local",
      "excerpt": "…",
      "excerpt_truncated": true,
      "url": "https://gocodebook.com/library/us/ca/san-jose/sections/…"
    }
  ],
  "notices": [],
  "usage": { "search": 1, "overview": 0 }
}

• citation is ready to show. url opens the full section on gocodebook.com — please link it next to any excerpt you display.
• query.jurisdiction.resolved_from says whether the scope came from your request, from a place named in the query, or the default.
• Section ids in the free sample can change when a code is re-collected. Store the citation and URL as well.

Notices

notices[] explains results that need explaining. Codes are stable; new ones may be added, so showmessage for a code you do not recognise.

AI overview (paid access)

With paid access, "include": ["overview"] adds an overview object to the response.overview.summary is the bottom line (about 350 characters), why the reasoning andcheck_next what would change the answer. Bracket markers like [2] map tooverview.citations; each carries a link and, when that section is also in results, itsresult_id. If the overview cannot run, overview.status says so and the results are still returned.

Jurisdictions

curl -s "https://gocodebook.com/api/v1/jurisdictions?q=san"

GET /v1/jurisdictions lists California cities and counties with their ids (q, level,limit). GET /v1/jurisdictions/{id} lists the local codes held for one, with when each was last collected.

Errors

{
  "error": {
    "type": "invalid_request",
    "code": "layer_not_available",
    "message": "The `subnational` layer is not available in the free sample yet; it serves local ordinances only.",
    "param": "filters.layers[0]"
  },
  "request_id": "req_…"
}

Questions

Coming next

• California state law, federal housing law and Title 24 building codes (excerpts).
• Topic filters (renting, buying and selling, development, HOAs, foreclosure, taxes).
• Stable section ids that survive a code being re-collected.
• More domains (business licensing, employment) and more states.

Contact

For higher limits, contract pricing, invoiced billing or a coverage question, write to support@gocodebook.com.