{"components":{"parameters":{"bbox":{"description":"Only permits inside a map box: `minLon,minLat,maxLon,maxLat`, at most 2 degrees each way.","in":"query","name":"bbox","schema":{"example":"-84.45,33.70,-84.30,33.82","type":"string"}},"cursor":{"description":"`next_cursor` from the previous page.","in":"query","name":"cursor","schema":{"type":"string"}},"geo_id":{"description":"A state (`GA`), 5-digit zip or county FIPS (`30319`, `13121`), jurisdiction slug (`ga/atlanta`), or any `geo_id` from `/v2/geography/search`.","in":"query","name":"geo_id","schema":{"type":"string"}},"geo_id_required":{"description":"A state (`GA`), county FIPS (`13121`), zip, jurisdiction slug (`ga/atlanta`), or a city `geo_id` from `/v2/geography/search`.","in":"query","name":"geo_id","required":true,"schema":{"type":"string"}},"include_count":{"description":"Add `total_count` to the first page (exact up to 10,000). Free.","in":"query","name":"include_count","schema":{"default":false,"type":"boolean"}},"lat":{"description":"With `lon` and `radius_m`: only permits within that distance of a point.","in":"query","name":"lat","schema":{"type":"number"}},"lon":{"in":"query","name":"lon","schema":{"type":"number"}},"month_from":{"description":"First month, `YYYY-MM`. Defaults to 24 months before `to` (12 for rankings).","in":"query","name":"from","schema":{"example":"2025-01","type":"string"}},"month_to":{"description":"Last month, `YYYY-MM`. Defaults to this month.","in":"query","name":"to","schema":{"example":"2026-09","type":"string"}},"permit_from":{"description":"Start of the permit-date range (issue date, else file date).","in":"query","name":"permit_from","required":true,"schema":{"example":"2025-01-01","format":"date","type":"string"}},"permit_to":{"in":"query","name":"permit_to","required":true,"schema":{"example":"2025-12-31","format":"date","type":"string"}},"radius_m":{"description":"Metres, up to 50,000.","in":"query","name":"radius_m","schema":{"maximum":50000,"type":"number"}},"size":{"in":"query","name":"size","schema":{"default":10,"maximum":100,"minimum":1,"type":"integer"}}},"responses":{"CreditsExhausted":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The monthly credit allowance is used up (`code: credits_exhausted`)."},"Error":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"401 missing/invalid/revoked key, 403 inactive subscription, 429 rate limited, 5xx server error."},"Invalid":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A parameter is missing or invalid."},"List":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{},"type":"array"}},"type":"object"}}},"description":"A reference list."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found."}},"schemas":{"Address":{"properties":{"city":{"type":["string","null"]},"county":{"type":["string","null"]},"county_fips":{"type":["string","null"]},"latlng":{"description":"[lat, lng]","items":{"type":"number"},"type":["array","null"]},"raw":{"description":"The address as the source printed it.","type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"street_no":{"type":["string","null"]},"unit":{"type":["string","null"]},"zip_code":{"type":["string","null"]},"zip_code_ext":{"type":["string","null"]}},"type":"object"},"AddressRecord":{"allOf":[{"$ref":"#/components/schemas/Address"},{"properties":{"cbsa":{"type":["string","null"]},"census_tract":{"type":["string","null"]},"geo_ids":{"type":"object"},"geocode_confidence":{"type":["number","null"]},"geocode_source":{"type":["string","null"]},"id":{"type":"string"},"parcel_id":{"type":["string","null"]},"permit_count":{"type":"integer"}},"type":"object"}]},"Allowance":{"properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"used":{"type":"integer"},"window_end":{"format":"date","type":"string"},"window_start":{"format":"date","type":"string"}},"type":"object"},"Contractor":{"properties":{"address_count":{"type":["integer","null"]},"avg_job_value":{"type":["integer","null"]},"city":{"type":["string","null"]},"classification_derived":{"items":{"type":"string"},"type":"array"},"classification_raw":{"type":["string","null"]},"dba":{"type":["string","null"]},"first_permit_date":{"format":"date","type":["string","null"]},"group_id":{"type":["string","null"]},"id":{"type":"string"},"is_representative":{"type":"boolean"},"jurisdiction_count":{"type":["integer","null"]},"last_permit_date":{"format":"date","type":["string","null"]},"license":{"type":["string","null"]},"license_board":{"type":["string","null"]},"license_expire_date":{"format":"date","type":["string","null"]},"license_state":{"type":["string","null"]},"license_type":{"type":["string","null"]},"license_verified":{"description":"Matched to a state license roster.","type":"boolean"},"median_job_value":{"type":["integer","null"]},"name":{"type":"string"},"permit_count":{"type":["integer","null"]},"state":{"type":["string","null"]},"status":{"type":["string","null"]},"status_tally":{"additionalProperties":{"type":"integer"},"type":"object"},"tag_tally":{"additionalProperties":{"type":"integer"},"type":"object"},"total_job_value":{"type":["integer","null"]},"zip":{"type":["string","null"]}},"type":"object"},"Decision":{"properties":{"address":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Address"}]},"agenda_number":{"type":["string","null"]},"attachments":{"items":{"type":"object"},"type":"array"},"body":{"description":"The council, board or commission.","type":["string","null"]},"category":{"type":["string","null"]},"description":{"type":["string","null"]},"extraction_method":{"enum":["rules","llm",null],"type":["string","null"]},"geo_ids":{"type":"object"},"id":{"type":"string"},"jurisdiction":{"type":"string"},"matter_id":{"type":["string","null"]},"meeting_date":{"format":"date","type":["string","null"]},"parcel_apn":{"type":["string","null"]},"parcel_id":{"type":["string","null"]},"property_cbsa":{"type":["string","null"]},"property_census_tract":{"type":["string","null"]},"source_url":{"type":["string","null"]},"status":{"type":["string","null"]},"status_raw":{"type":["string","null"]},"subcategory":{"type":["string","null"]},"title":{"type":["string","null"]},"updated_at":{"format":"date-time","type":["string","null"]},"vote_result":{"type":["string","null"]},"zoning_from":{"type":["string","null"]},"zoning_to":{"type":["string","null"]}},"type":"object"},"Error":{"properties":{"code":{"description":"Stable reason to branch on.","enum":["credits_exhausted","export_rows_exhausted","rate_limited","key_revoked","subscription_inactive"],"type":"string"},"detail":{"type":"string"},"request_id":{"description":"Quote this when contacting support.","type":"string"}},"required":["detail"],"type":"object"},"Page":{"properties":{"items":{"items":{},"type":"array"},"next_cursor":{"type":["string","null"]},"size":{"type":"integer"},"total_count":{"properties":{"relation":{"enum":["eq","gte"],"type":"string"},"value":{"type":"integer"}},"type":"object"}},"required":["items","size","next_cursor"],"type":"object"},"Permit":{"properties":{"address":{"oneOf":[{"type":"null"},{"allOf":[{"$ref":"#/components/schemas/Address"},{"properties":{"jurisdiction":{"type":"string"}},"type":"object"}]}]},"approval_duration":{"description":"Days from filing to issue.","type":["integer","null"]},"construction_duration":{"description":"Days from issue to final.","type":["integer","null"]},"contractor":{"properties":{"classification":{"items":{"type":"string"},"type":"array"},"group_id":{"type":["string","null"]},"id":{"type":"string"},"license":{"type":["string","null"]},"license_state":{"type":["string","null"]},"license_type":{"type":["string","null"]},"name":{"type":"string"},"permit_count":{"type":["integer","null"]}},"type":["object","null"]},"contractor_id":{"type":["string","null"]},"contractor_license":{"type":["string","null"]},"contractor_name":{"type":["string","null"]},"description":{"type":["string","null"]},"expire_date":{"format":"date","type":["string","null"]},"fees":{"description":"Cents.","type":["integer","null"]},"file_date":{"format":"date","type":["string","null"]},"final_date":{"format":"date","type":["string","null"]},"geo_ids":{"properties":{"address_id":{"type":["string","null"]},"city_id":{"type":["string","null"]},"county_id":{"type":["string","null"]},"jurisdiction_id":{"type":"string"},"state_id":{"type":"string"}},"type":"object"},"id":{"description":"Stable across refreshes.","type":"string"},"issue_date":{"format":"date","type":["string","null"]},"job_value":{"description":"Declared valuation, cents.","type":["integer","null"]},"jurisdiction":{"type":"string"},"number":{"type":"string"},"parcel_apn":{"type":["string","null"]},"property":{"description":"Assessor facts for the linked parcel.","properties":{"apn":{"type":["string","null"]},"appraised_value":{"type":["integer","null"]},"assessed_value":{"type":["integer","null"]},"building_area":{"type":["number","null"]},"id":{"type":"string"},"land_use":{"type":["string","null"]},"lot_size":{"type":["number","null"]},"owner_type":{"type":["string","null"]},"type":{"type":["string","null"]},"units":{"type":["integer","null"]},"year_built":{"type":["integer","null"]}},"type":["object","null"]},"property_cbsa":{"type":["string","null"]},"property_census_tract":{"type":["string","null"]},"property_type":{"type":["string","null"]},"property_use_raw":{"type":["string","null"]},"source_url":{"type":["string","null"]},"status":{"enum":["in_review","active","final","inactive",null],"type":["string","null"]},"status_raw":{"type":["string","null"]},"subtype":{"type":["string","null"]},"tags":{"items":{"type":"string"},"type":"array"},"total_duration":{"type":["integer","null"]},"type":{"type":["string","null"]},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"Property":{"properties":{"address":{"$ref":"#/components/schemas/Address"},"address_id":{"type":["string","null"]},"apn":{"type":"string"},"appraised_improvement_value":{"type":["integer","null"]},"appraised_land_value":{"type":["integer","null"]},"appraised_value":{"type":["integer","null"]},"assessed_improvement_value":{"type":["integer","null"]},"assessed_land_value":{"type":["integer","null"]},"assessed_value":{"type":["integer","null"]},"assessment_year":{"type":["integer","null"]},"building_area":{"type":["number","null"]},"class_code":{"type":["string","null"]},"county_fips":{"type":"string"},"id":{"type":"string"},"land_use":{"type":["string","null"]},"land_use_code":{"type":["string","null"]},"lot_size":{"type":["number","null"]},"lot_size_acres":{"type":["number","null"]},"owner_type":{"type":["string","null"]},"permit_count":{"type":"integer"},"property_type":{"type":["string","null"]},"source":{"type":["string","null"]},"stories":{"type":["number","null"]},"units":{"type":["integer","null"]},"updated_at":{"format":"date-time","type":["string","null"]},"year_built":{"type":["integer","null"]}},"type":"object"},"SystemAge":{"properties":{"age_years":{"type":["number","null"]},"basis":{"enum":["permit","year_built","unknown"],"type":"string"},"label":{"type":"string"},"last_permit_id":{"type":["string","null"]},"last_work_date":{"format":"date","type":["string","null"]},"lifespan_years":{"type":"integer"},"permit_count":{"type":"integer"},"remaining_years":{"type":["number","null"]},"status":{"description":"due at the end of its lifespan, mid from 60% of it.","enum":["recent","mid","due","unknown"],"type":"string"},"system":{"enum":["roof","hvac","water_heater","plumbing","electrical","windows"],"type":"string"}},"type":"object"}},"securitySchemes":{"apiKey":{"in":"header","name":"X-API-Key","type":"apiKey"}}},"info":{"contact":{"name":"OpenPermits","url":"https://openpermits.ai"},"description":"Paths and parameter names follow the Shovels v2 API where it makes sense, so existing\nclient code can switch with a base-URL change.\n\n**Authentication.** Send your key in the `X-API-Key` header. Keys are secrets for your\nservers: the API sends no CORS headers, so browser calls fail by design.\n\n**Credits.** Data endpoints cost one credit per record returned (one per single-record\nlookup). Empty results and `include_count` are free, as are the reference endpoints\n(`/v2/list/*`, geography, jurisdictions, `/v2/meta/*`, `/v2/usage`). Every charged\nresponse reports your allowance in `X-Credits-Charged`, `X-Credits-Used`,\n`X-Credits-Limit`, `X-Credits-Remaining` and `X-Credits-Reset`. When the monthly allowance\nis used up, data endpoints return `402` with `code: credits_exhausted` until it resets.\n\n**Rate limits.** Requests over your plan's per-second limit return `429` with\n`Retry-After`.\n\n**Pagination.** List endpoints return `next_cursor`; pass it back as `cursor` to get the\nnext page. `size` is at most 100.\n\n**Money** is in cents. **Dates** are `YYYY-MM-DD`.\n\n**Personal data.** OpenPermits sells property records, not personal data: owner and\napplicant names and contact phone numbers are never returned.\n","summary":"Building permits, contractors, properties and zoning decisions.","title":"OpenPermits API","version":"2.0.0"},"openapi":"3.1.0","paths":{"/v2/addresses/search":{"get":{"operationId":"searchAddresses","parameters":[{"description":"Free-text address; fuzzy-matched.","in":"query","name":"address_q","schema":{"example":"55 Trinity Ave SW","type":"string"}},{"$ref":"#/components/parameters/geo_id"},{"description":"Only addresses with at least one permit.","in":"query","name":"with_permits","schema":{"default":true,"type":"boolean"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/AddressRecord"},"type":"array"}},"type":"object"}]}}},"description":"A page of addresses.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"default":{"$ref":"#/components/responses/Error"}},"summary":"Search addresses","tags":["Addresses"]}},"/v2/addresses/{address_id}/systems":{"get":{"description":"For each building system, the last permitted work on it and how far through its typical\nlifespan it is. Where no permit is on record, the building's year built (from its\nassessor parcel) stands in, and the basis says so. Lifespans: roof 20 years, HVAC 15,\nwater heater 10, plumbing 40, electrical 30, windows and doors 25. One credit.\n","operationId":"addressSystems","parameters":[{"in":"path","name":"address_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"address":{"$ref":"#/components/schemas/AddressRecord"},"address_id":{"type":"string"},"as_of":{"format":"date","type":"string"},"systems":{"items":{"$ref":"#/components/schemas/SystemAge"},"type":"array"},"year_built":{"type":["integer","null"]}},"type":"object"}}},"description":"Systems.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"How old an address's roof, HVAC and other systems are","tags":["Properties"]}},"/v2/contractors/rankings":{"get":{"description":"The contractors pulling the most permits in a geography and period, with their share of all permits there, including permits that name no contractor. One credit per contractor returned.","operationId":"contractorRankings","parameters":[{"$ref":"#/components/parameters/geo_id_required"},{"description":"One work-type tag, or `*` (the default) for all permits.","in":"query","name":"tag","schema":{"default":"*","type":"string"}},{"$ref":"#/components/parameters/month_from"},{"$ref":"#/components/parameters/month_to"},{"in":"query","name":"size","schema":{"default":25,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"from":{"example":"2025-10","type":"string"},"geo_id":{"type":"string"},"items":{"items":{"properties":{"contractor":{"properties":{"classification":{"items":{"type":"string"},"type":"array"},"group_id":{"type":["string","null"]},"id":{"type":"string"},"license":{"type":["string","null"]},"license_state":{"type":["string","null"]},"license_verified":{"type":"boolean"},"name":{"type":["string","null"]}},"type":"object"},"job_value_share":{"type":["number","null"]},"job_value_total":{"type":["integer","null"]},"permit_count":{"type":"integer"},"permit_share":{"description":"Fraction of the market's permits, 0-1.","type":["number","null"]},"rank":{"type":"integer"}},"type":"object"},"type":"array"},"market":{"properties":{"job_value_total":{"type":"integer"},"permit_count":{"type":"integer"}},"type":"object"},"tag":{"type":"string"},"to":{"example":"2026-09","type":"string"}},"type":"object"}}},"description":"Rankings.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"422":{"$ref":"#/components/responses/Invalid"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Contractors by market share","tags":["Markets"]}},"/v2/contractors/search":{"get":{"description":"Sorted by permit count, highest first. Returns one representative per dedup group unless `include_members`.","operationId":"searchContractors","parameters":[{"$ref":"#/components/parameters/geo_id"},{"description":"Text in the name or DBA.","in":"query","name":"contractor_q","schema":{"type":"string"}},{"description":"Comma-separated classes (`/v2/list/contractor_classifications`).","in":"query","name":"contractor_classification","schema":{"example":"roofing,hvac","type":"string"}},{"description":"License number, punctuation-insensitive.","in":"query","name":"contractor_license","schema":{"type":"string"}},{"in":"query","name":"contractor_min_permit_count","schema":{"type":"integer"}},{"in":"query","name":"include_members","schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/include_count"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/Contractor"},"type":"array"}},"type":"object"}]}}},"description":"A page of contractors.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Search contractors","tags":["Contractors"]}},"/v2/contractors/{contractor_id}":{"get":{"operationId":"getContractor","parameters":[{"in":"path","name":"contractor_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Contractor"},{"properties":{"group":{"description":"Totals across every branch of the same business.","properties":{"avg_job_value":{"type":["integer","null"]},"first_permit_date":{"format":"date","type":["string","null"]},"group_id":{"type":"string"},"last_permit_date":{"format":"date","type":["string","null"]},"member_count":{"type":"integer"},"permit_count":{"type":"integer"},"total_job_value":{"type":["integer","null"]}},"type":"object"},"jurisdictions":{"items":{"properties":{"name":{"type":"string"},"permits":{"type":"integer"},"slug":{"type":"string"}},"type":"object"},"type":"array"},"members":{"items":{"properties":{"id":{"type":"string"},"is_representative":{"type":"boolean"},"license":{"type":["string","null"]},"license_state":{"type":["string","null"]},"name":{"type":"string"},"permit_count":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"}]}}},"description":"The contractor.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Get a contractor, with its group and jurisdictions","tags":["Contractors"]}},"/v2/contractors/{contractor_id}/permits":{"get":{"operationId":"contractorPermits","parameters":[{"in":"path","name":"contractor_id","required":true,"schema":{"type":"string"}},{"description":"Include every branch in the contractor's group.","in":"query","name":"include_group","schema":{"default":false,"type":"boolean"}},{"in":"query","name":"permit_from","schema":{"format":"date","type":"string"}},{"in":"query","name":"permit_to","schema":{"format":"date","type":"string"}},{"in":"query","name":"permit_tags","schema":{"type":"string"}},{"in":"query","name":"permit_status","schema":{"type":"string"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/include_count"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/Permit"},"type":"array"}},"type":"object"}]}}},"description":"A page of permits.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"List a contractor's permits","tags":["Contractors"]}},"/v2/decisions/search":{"get":{"operationId":"searchDecisions","parameters":[{"in":"query","name":"meeting_from","required":true,"schema":{"format":"date","type":"string"}},{"in":"query","name":"meeting_to","required":true,"schema":{"format":"date","type":"string"}},{"$ref":"#/components/parameters/geo_id"},{"description":"Comma-separated (`/v2/list/decision_categories`).","in":"query","name":"category","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"zoning_from","schema":{"type":"string"}},{"in":"query","name":"zoning_to","schema":{"type":"string"}},{"description":"Text in the title or description.","in":"query","name":"q","schema":{"type":"string"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/include_count"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/Decision"},"type":"array"}},"type":"object"}]}}},"description":"A page of decisions.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"default":{"$ref":"#/components/responses/Error"}},"summary":"Search zoning and land-use decisions","tags":["Decisions"]}},"/v2/decisions/{decision_id}":{"get":{"operationId":"getDecision","parameters":[{"in":"path","name":"decision_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}},"description":"The decision.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Get a decision","tags":["Decisions"]}},"/v2/geography/search":{"get":{"operationId":"searchGeography","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"kind","schema":{"enum":["state","county","city","zip","jurisdiction"],"type":"string"}},{"in":"query","name":"size","schema":{"default":20,"maximum":200,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"geo_id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"state":{"type":["string","null"]}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Matching geographies."},"default":{"$ref":"#/components/responses/Error"}},"summary":"Find a geo_id for a state, county, city, zip or jurisdiction","tags":["Reference"]}},"/v2/jurisdictions/search":{"get":{"operationId":"searchJurisdictions","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"size","schema":{"default":50,"maximum":500,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"county":{"type":["string","null"]},"earliest":{"format":"date","type":["string","null"]},"geo_id":{"type":"string"},"latest":{"format":"date","type":["string","null"]},"name":{"type":"string"},"permit_count":{"type":"integer"},"slug":{"type":"string"},"state":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Jurisdictions."},"default":{"$ref":"#/components/responses/Error"}},"summary":"List covered jurisdictions, with permit counts and date ranges","tags":["Reference"]}},"/v2/list/contractor_classifications":{"get":{"operationId":"listContractorClassifications","responses":{"200":{"$ref":"#/components/responses/List"}},"summary":"Contractor classes","tags":["Reference"]}},"/v2/list/decision_categories":{"get":{"operationId":"listDecisionCategories","responses":{"200":{"$ref":"#/components/responses/List"}},"summary":"Decision categories","tags":["Reference"]}},"/v2/list/property_types":{"get":{"operationId":"listPropertyTypes","responses":{"200":{"$ref":"#/components/responses/List"}},"summary":"Property types","tags":["Reference"]}},"/v2/list/tags":{"get":{"operationId":"listTags","responses":{"200":{"$ref":"#/components/responses/List"}},"summary":"Work-type tags","tags":["Reference"]}},"/v2/markets/metrics":{"get":{"description":"Permit counts, job value (total and median), average approval time and active contractors per month, overall or for up to six work-type tags. Months with no permits are omitted. One credit per row.","operationId":"marketMetrics","parameters":[{"$ref":"#/components/parameters/geo_id_required"},{"description":"Comma-separated work-type tags, or `*` (the default) for all permits.","in":"query","name":"tag","schema":{"default":"*","example":"ROOFING,SOLAR","type":"string"}},{"$ref":"#/components/parameters/month_from"},{"$ref":"#/components/parameters/month_to"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"from":{"type":"string"},"geo_id":{"type":"string"},"geo_kind":{"enum":["state","jurisdiction","county","city","zip"],"type":"string"},"items":{"items":{"properties":{"approval_days_avg":{"type":["number","null"]},"contractor_count":{"type":"integer"},"job_value_median":{"description":"Cents.","type":["integer","null"]},"job_value_total":{"description":"Cents.","type":["integer","null"]},"month":{"example":"2026-08","type":"string"},"permit_count":{"type":"integer"},"tag":{"type":"string"}},"type":"object"},"type":"array"},"size":{"type":"integer"},"to":{"type":"string"}},"type":"object"}}},"description":"Monthly rows, ordered by tag then month.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"422":{"$ref":"#/components/responses/Invalid"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Monthly permit activity for a place","tags":["Markets"]}},"/v2/meta/coverage":{"get":{"operationId":"coverage","parameters":[{"$ref":"#/components/parameters/permit_from"},{"$ref":"#/components/parameters/permit_to"},{"$ref":"#/components/parameters/geo_id"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"field":{"type":"string"},"fill_pct":{"type":"number"},"permits_total":{"type":"integer"},"tier":{"description":"reliable \u003e= 80%, partial \u003e= 10%","enum":["reliable","partial","missing"],"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Fill rates."}},"summary":"How often each permit field is filled, for a place and period","tags":["Reference"]}},"/v2/meta/release":{"get":{"operationId":"releaseDate","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"last_crawl":{"format":"date-time","type":["string","null"]},"last_decisions":{"format":"date-time","type":["string","null"]},"last_normalize":{"format":"date-time","type":["string","null"]},"last_parcels":{"format":"date-time","type":["string","null"]},"last_resolve":{"format":"date-time","type":["string","null"]},"settled_through":{"description":"Every permit first seen before this time has been fully processed (geocoded, linked to its parcel and contractor). Newer permits may still gain fields.","format":"date-time","type":["string","null"]}},"type":"object"}}},"description":"Timestamps."}},"summary":"When each part of the data was last refreshed","tags":["Reference"]}},"/v2/permits/export.csv":{"get":{"description":"The same filters as `/v2/permits/search`, streamed as one CSV file, newest first. Costs one\ncredit per row. The export stops at your remaining allowance or `limit`, whichever is\nsmaller; `X-Export-Row-Limit` says which. Text cells that a spreadsheet would run as a\nformula are prefixed with an apostrophe.\n","operationId":"exportPermits","parameters":[{"$ref":"#/components/parameters/permit_from"},{"$ref":"#/components/parameters/permit_to"},{"$ref":"#/components/parameters/geo_id"},{"in":"query","name":"permit_tags","schema":{"type":"string"}},{"in":"query","name":"permit_status","schema":{"type":"string"}},{"in":"query","name":"permit_q","schema":{"maxLength":50,"minLength":3,"type":"string"}},{"in":"query","name":"permit_min_job_value","schema":{"type":"integer"}},{"in":"query","name":"property_type","schema":{"type":"string"}},{"in":"query","name":"contractor_id","schema":{"type":"string"}},{"in":"query","name":"address_id","schema":{"type":"string"}},{"in":"query","name":"updated_since","schema":{"type":"string"}},{"in":"query","name":"first_seen_since","schema":{"type":"string"}},{"in":"query","name":"first_seen_before","schema":{"type":"string"}},{"$ref":"#/components/parameters/bbox"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/radius_m"},{"description":"At most this many rows.","in":"query","name":"limit","schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"CSV with columns id, number, type, subtype, description, status, file_date, issue_date, final_date, job_value_cents, fees_cents, tags (pipe-separated), street_no, street, unit, city, state, zip, latitude, longitude, census_tract, jurisdiction, property_type, parcel_apn, contractor_id, contractor_name, contractor_license, source_url, updated_at.","headers":{"X-Export-Row-Limit":{"description":"The most rows this export could contain.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"422":{"$ref":"#/components/responses/Invalid"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Export permits as CSV","tags":["Permits"]}},"/v2/permits/search":{"get":{"description":"Newest first by permit date (issue date, else file date).","operationId":"searchPermits","parameters":[{"$ref":"#/components/parameters/permit_from"},{"$ref":"#/components/parameters/permit_to"},{"$ref":"#/components/parameters/geo_id"},{"description":"Comma-separated tags (`/v2/list/tags`). Prefix a tag with `-` to exclude it.","in":"query","name":"permit_tags","schema":{"example":"ROOFING,-SOLAR","type":"string"}},{"description":"Comma-separated statuses.","in":"query","name":"permit_status","schema":{"example":"active,final","type":"string"}},{"description":"Text in the description or type, 3 to 50 characters.","in":"query","name":"permit_q","schema":{"maxLength":50,"minLength":3,"type":"string"}},{"description":"Minimum declared job value, in cents.","in":"query","name":"permit_min_job_value","schema":{"type":"integer"}},{"description":"Exact permit number, case-insensitive. `%` and `_` act as wildcards.","in":"query","name":"permit_number","schema":{"type":"string"}},{"description":"Comma-separated property types (`/v2/list/property_types`).","in":"query","name":"property_type","schema":{"type":"string"}},{"in":"query","name":"contractor_id","schema":{"type":"string"}},{"description":"Every permit at one address (`geo_ids.address_id` on a permit, or `id` from `/v2/addresses/search`).","in":"query","name":"address_id","schema":{"type":"string"}},{"description":"Only permits created or changed since this time (RFC 3339 or a date). For incremental syncs.","in":"query","name":"updated_since","schema":{"type":"string"}},{"description":"Only permits we first saw since this time (RFC 3339 or a date). Unlike `updated_since`, status changes don't count.","in":"query","name":"first_seen_since","schema":{"type":"string"}},{"description":"Only permits we first saw before this time (exclusive). For gap-free polling, request `first_seen_since` = your last cutoff and `first_seen_before` = `settled_through` from `/v2/meta/release`, then keep that value as your next cutoff.","in":"query","name":"first_seen_before","schema":{"type":"string"}},{"$ref":"#/components/parameters/bbox"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/radius_m"},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/include_count"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/Permit"},"type":"array"}},"type":"object"}]}}},"description":"A page of permits.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"422":{"$ref":"#/components/responses/Invalid"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Search permits","tags":["Permits"]}},"/v2/permits/{permit_id}":{"get":{"operationId":"getPermit","parameters":[{"in":"path","name":"permit_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Permit"},{"properties":{"status_history":{"items":{"properties":{"observed_at":{"format":"date-time","type":"string"},"status":{"type":["string","null"]},"status_date":{"format":"date","type":["string","null"]},"status_raw":{"type":["string","null"]}},"type":"object"},"type":"array"}},"type":"object"}]}}},"description":"The permit.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Get a permit, with its status history","tags":["Permits"]}},"/v2/properties/search":{"get":{"operationId":"searchProperties","parameters":[{"$ref":"#/components/parameters/geo_id"},{"in":"query","name":"property_type","schema":{"type":"string"}},{"description":"`individual`, `business`, `government`, ...","in":"query","name":"owner_type","schema":{"type":"string"}},{"in":"query","name":"apn","schema":{"type":"string"}},{"in":"query","name":"min_year_built","schema":{"type":"integer"}},{"in":"query","name":"max_year_built","schema":{"type":"integer"}},{"in":"query","name":"with_permits","schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/Property"},"type":"array"}},"type":"object"}]}}},"description":"A page of properties.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"default":{"$ref":"#/components/responses/Error"}},"summary":"Search properties (assessor parcels)","tags":["Properties"]}},"/v2/properties/{parcel_id}":{"get":{"operationId":"getProperty","parameters":[{"in":"path","name":"parcel_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Property"},{"properties":{"permits":{"items":{"properties":{"contractor_id":{"type":["string","null"]},"id":{"type":"string"},"job_value":{"type":["integer","null"]},"number":{"type":"string"},"permit_date":{"format":"date","type":["string","null"]},"status":{"type":["string","null"]},"tags":{"items":{"type":"string"},"type":"array"},"type":{"type":["string","null"]}},"type":"object"},"type":"array"},"systems":{"description":"Building-system ages at the property's address (see `/v2/addresses/{address_id}/systems`).","items":{"$ref":"#/components/schemas/SystemAge"},"type":["array","null"]}},"type":"object"}]}}},"description":"The property.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Get a property, with up to 50 of its permits and its system ages","tags":["Properties"]}},"/v2/signals/aging-systems":{"get":{"description":"Addresses in a place where a building system is older than `min_age_years` (by default its\ntypical lifespan). The evidence is either the last permit for that system (`basis:\npermit`) or, where there is none, the building's year built (`basis: year_built`,\nwherever assessor parcels are loaded). One credit per address.\n","operationId":"agingSystems","parameters":[{"$ref":"#/components/parameters/geo_id_required"},{"in":"query","name":"system","required":true,"schema":{"enum":["roof","hvac","water_heater","plumbing","electrical","windows"],"type":"string"}},{"in":"query","name":"min_age_years","schema":{"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"basis","schema":{"default":"all","enum":["all","permit","year_built"],"type":"string"}},{"description":"Comma-separated (`/v2/list/property_types`).","in":"query","name":"property_type","schema":{"type":"string"}},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"items":{"properties":{"address":{"$ref":"#/components/schemas/AddressRecord"},"address_id":{"type":"string"},"age_years":{"type":"number"},"basis":{"enum":["permit","year_built"],"type":"string"},"last_permit_id":{"type":["string","null"]},"last_work_date":{"format":"date","type":["string","null"]},"lifespan_years":{"type":"integer"},"property_type":{"type":["string","null"]},"system":{"type":"string"},"year_built":{"type":["integer","null"]}},"type":"object"},"type":"array"}},"type":"object"}]}}},"description":"A page of addresses.","headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}},"402":{"$ref":"#/components/responses/CreditsExhausted"},"422":{"$ref":"#/components/responses/Invalid"},"default":{"$ref":"#/components/responses/Error"}},"summary":"Addresses whose roof, HVAC or other system is getting old","tags":["Signals"]}},"/v2/usage":{"get":{"operationId":"usage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"credits":{"$ref":"#/components/schemas/Allowance"},"export_rows":{"$ref":"#/components/schemas/Allowance"},"org_id":{"type":"string"},"rate_limit_rps":{"type":"integer"}},"type":"object"}}},"description":"Usage."},"default":{"$ref":"#/components/responses/Error"}},"summary":"Your allowances in the current monthly window","tags":["Account"]}}},"security":[{"apiKey":[]}],"servers":[{"url":"https://api.openpermits.ai"}],"tags":[{"name":"Permits"},{"name":"Contractors"},{"name":"Properties"},{"name":"Addresses"},{"description":"Zoning and land-use agenda items from city and county bodies.","name":"Decisions"},{"description":"Monthly permit activity and contractor market share for a geography, recomputed after every data refresh.","name":"Markets"},{"description":"Ready-made lead and risk lists built from permit history.","name":"Signals"},{"name":"Reference"},{"name":"Account"}],"x-credit-headers":{"X-Credits-Charged":{"description":"Credits this response cost.","schema":{"type":"integer"}},"X-Credits-Limit":{"description":"Credits included per window.","schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Date the window resets.","schema":{"format":"date","type":"string"}},"X-Credits-Used":{"description":"Credits used this window.","schema":{"type":"integer"}}}}