--- title: "Search permits" method: GET path: "/v1/permit" tags: ["permit"] --- # Search permits `GET /v1/permit` ## Request - Base URL: `http://localhost:3030` - URL: `http://localhost:3030/v1/permit` - Auth: HTTP bearer Searches building and trade permits by place, parcel or area. Requires one of `jurisdiction`, `fips`, `parcel`, `bbox`, or `lat` with `lon`. A permit is decided when it is issued or refused. `decided=false` limits results to pending permits. The outcome is the permit's status, so a permit issued and since expired is decided, with the outcome `Expired`. ## Query parameters - `jurisdiction` string, nullable: A jurisdiction id. - `fips` string, nullable: A Census GEOID: 2 digits for a state or 5 for a county, such as `48` or `48453`. Results are limited to permits that lie within it. - `parcel` string, nullable: A parcel id. - `lat` number, nullable: Latitude, in WGS 84. Requires `lon`. Results are permits with an address within `radius`. - `lon` number, nullable: Longitude, in WGS 84. Requires `lat`. - `radius` number, nullable: Search radius around `lat` and `lon`, in meters. At most 25,000. Defaults to 1,000. - `bbox` string, nullable: A bounding box, as `west,south,east,north` in WGS 84. Results are limited to permits with an address inside it. - `type` string, nullable: Permit type code, as published. - `status` string, nullable: Status code, as published. - `outcome` string, nullable: Decision outcome code, as published. - `decided` boolean, nullable: Whether the permit has a decision. `false` returns pending permits. - `party` string, nullable: A name on the permit, or words from it. Results are permits with a party name containing every word. - `q` string, nullable: Words from the permit description. Results are ordered best match first. - `min_applied` string, nullable: Earliest application date, as `YYYY-MM-DD`. - `max_applied` string, nullable: Latest application date, as `YYYY-MM-DD`. - `min_decided` string, nullable: Earliest decision date, as `YYYY-MM-DD`. - `max_decided` string, nullable: Latest decision date, as `YYYY-MM-DD`. - `min_valuation` number, nullable: Minimum declared value. Permits without a declared value never match. - `max_valuation` number, nullable: Maximum declared value. Permits without a declared value never match. - `sort` string, nullable: Sort order. One of `applied`, `as_of`, `decided`, `issued`, `valuation`. Prefix with `-` for descending. Not accepted with `q`. - `cursor` string, nullable: A cursor for pagination: the `next_cursor` from the previous page. - `size` integer, nullable: Number of results per page, between 1 and 200. Defaults to 20. - `total` boolean: Whether to include `total`, the count of all matches, on the first page. Defaults to `false`. ## Response `200` A page of permits. - CollectionPermit - `object` 'list', required: The object's type. Always `list`. - `data` Permit[], required: The results on this page. - `object` 'permit', required: The object's type. Always `permit`. - `id` string, required: A permit id. - `number` string, nullable, required: Permit number, as published. Null when not published. - `type` Code, required: A coded value, as published, with its standard equivalent. - `code` string, nullable: Code, as published. - `description` string, nullable: Meaning of the code, as published. Null when not published. - `standard` string, nullable: Standard value, shared across jurisdictions. Null when not yet classified. - `status` Code, required: A coded value, as published, with its standard equivalent. - `code` string, nullable: Code, as published. - `description` string, nullable: Meaning of the code, as published. Null when not published. - `standard` string, nullable: Standard value, shared across jurisdictions. Null when not yet classified. - `jurisdiction` ApplicationJurisdictionRef, required: The jurisdiction a permit or case was filed with. - `id` string, required: A jurisdiction id. - `name` string, required: The jurisdiction's common name. - `type` string, required: Kind of jurisdiction, in local terms, such as `county`, `parish`, `city` or `town`. - `fips` string, nullable: The Census GEOID. Null outside the US. - `href` string, required: The object's path in the API. - `within` ApplicationWithin[], required: The jurisdictions that contain `jurisdiction`, largest first. - `id` string, required: A jurisdiction id. - `name` string, required: The jurisdiction's common name. - `tier` string, required: Level of government. One of `national`, `region` (a state or province), `subregion` (a county or district) or `local` (a city, town, village or township). - `type` string, required: Kind of jurisdiction, in local terms, such as `county`, `parish`, `city` or `town`. - `fips` string, nullable: The Census GEOID. Null outside the US. - `agency` Agency, required: The office or board that handled a permit or case. - `name` string, required: Office name, as published. - `type` string, nullable: Office type, such as `building`, `planning`, `zoning_board` or `commission`. Null when not published. - `description` string, nullable, required: Description of the work, as published. Null when not published. - `parcels` ParcelRef[], required: Parcels the permit concerns. Empty when none are matched, which is common when only an address is published. - `id` string, required: A parcel id. - `number` string, nullable: Primary parcel number. Null when not published. - `href` string, required: The object's path in the API. - `addresses` Address[], required: Addresses on the permit. Empty when none are published. - `raw` string, required: Full address on one line: every line it is published on, in order, joined with a comma. - `recipient` string, nullable: Care-of or attention line, as published. Null when there is none. - `street_line_1` string, nullable: First street line: house number and street, or a PO box. Null when not published. - `street_line_2` string, nullable: Second street line: apartment, suite, unit or building. Null when there is none. - `street_number` string, nullable: House number. Null when not published. - `street_name` string, nullable: Street name, without its type. Null when not published. - `unit` string, nullable: Unit number. Null when there is none. - `locality` string, nullable: City, town or village. Null when not published. - `region` string, nullable: State, as its two-letter abbreviation. Null when not published. - `postal_code` string, nullable: ZIP or postal code. Null when not published. - `point` ParcelPoint: A point in WGS 84. - `lat` number, required: Latitude, in WGS 84. - `lon` number, required: Longitude, in WGS 84. - `parties` Party[], required: People and companies named on the permit. Empty when none are published. - `name` string, required: Name, as published. - `role` string, nullable: Role, such as `applicant`, `owner`, `contractor`, `architect`, `engineer` or `representative`. Null when not published. - `organization` string, nullable: Company or organization represented. Null when not published. - `license` string, nullable: License number. Null when not published. - `dates` PermitDates, required: Key dates of a permit, as published. - `applied` string, date, nullable: Application date. Null when not published. - `issued` string, date, nullable: Issue date. Null when not issued or not published. - `decided` string, date, nullable: Decision date: the issue date, or the date of a denial. Null when not decided. - `expires` string, date, nullable: Expiration date. Null when not published. - `completed` string, date, nullable: Completion date of the work. Null when not published. - `valuation` Valuation, required: The declared value of the work. - `amount` number, required: Amount, in `currency`. - `currency` string, required: ISO 4217 currency code. - `fees` Fee[], required: Fees, by category. Empty when none are published. - `category` string, required: Fee category, such as `building`, `zoning`, `plan_review` or `impact`. `total` is all fees combined, present only when no fee is published by category. - `total` number, nullable: Amount charged. Null when not published. - `paid` number, nullable: Amount paid. Null when not published. - `unpaid` number, nullable: Amount outstanding. Null when not published. - `waived` number, nullable: Amount waived. Null when not published. - `currency` string, nullable: ISO 4217 currency code. Null when no amount is published. - `decision` Decision, required: The decision on a permit or case. - `outcome` Code, required: A coded value, as published, with its standard equivalent. - `code` string, nullable: Code, as published. - `description` string, nullable: Meaning of the code, as published. Null when not published. - `standard` string, nullable: Standard value, shared across jurisdictions. Null when not yet classified. - `decided_on` string, date, nullable: Decision date. Null when not published. - `effective_from` string, date, nullable: Effective date. Null when not published. - `effective_to` string, date, nullable: End date. Null while in effect. - `conditions` Condition[], required: Conditions of approval, as published. Empty when there are none. A listed condition is not necessarily met. - `text` string, required: Condition text, as published. - `scope` string, nullable: What the condition applies to, as published. Null when not stated. - `timing` string, nullable: When the condition must be met, such as `before_permit`, `before_occupancy` or `ongoing`. Null when not stated. - `due` string, date, nullable: Due date. Null when not stated. - `document` Document, required: The published record of a permit or case. - `url` string, nullable: URL of the published record. Null when not published. - `retrieved` string, date, nullable: Date the record was retrieved. Null when not recorded. - `as_of` string, date, nullable, required: Date of the most recent update to this permit. Null when not recorded. - `href` string, required: The object's path in the API. - `has_more` boolean, required: Whether there are more results after this page. - `next_cursor` string, nullable, required: The cursor for the next page. Send it as `cursor`. Null on the last page. - `suppressed` integer, required: The number of matching results withheld because the plan does not include them. - `total` Total, required: The number of matching results. - `value` integer, required: The number of matching results. - `relation` 'eq' | 'gte', required: One of `eq` (exact) or `gte` (at least `value`). Counts above 10,000 are `gte`. ## Other responses - `401`: `credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential. - `403`: `scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason. - `422`: `parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one. - `429`: `rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged. - `501`: `not_available`. Permit and case data is not available yet. --- [API](https://skmtc.dev/placestack/apis/placestack-api.md) · [All operations](https://skmtc.dev/placestack/apis/placestack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placestack/apis/placestack-api/revisions/0ccdf0882668?raw)