Permits

Search permits

GET

https://api.mykukun.com

/v1/permits/search

Search across Kukun's 650M+ U.S. permit records with full-text query, geo, status, label, and date filters. Returns enriched permit records including project labels (Kukun taxonomy), inferred activity labels, and contractor linkage where available.

Search permits › query Parameters

status

string · enum

Permit status filter. Use lowercase kebab-case values only.

Enum values:

applied

issued

in-process

denied

closed

review

expired

inspection

label

string

Comma-delimited label filters. Syntax: No prefix = OR include (any label matches), +prefix or !prefix = required include (AND — all must match), -prefix = exclude. Example: kitchen-remodel, bathroom-remodel returns permits labeled kitchen-remodel and excludes any labeled bathroom-remodel.

address

string · maxLength: 500

Street address filter (flexible AND match, e.g. 2601 Leaning Pine Ln)

city

string · maxLength: 200

City name filter (exact match, case-insensitive). Example: Tampa.

state

string · maxLength: 200

State name filter (exact match, e.g. Florida)

zip-code

string · maxLength: 10

ZIP code filter (exact match, e.g. 33565)

county

string · maxLength: 200

County name filter (exact match, e.g. Hillsborough)

jurisdiction

string · maxLength: 200

Issuing jurisdiction — matched against both city and county fields (e.g. Los Angeles)

latitude

number · min: -90 · max: 90

Center point latitude for geo-distance filtering. Requires longitude and distance. Example: 28.0614426.

longitude

number · min: -180 · max: 180

Center point longitude for geo-distance filtering. Requires latitude and distance. Example: -82.150608.

distance

number · min: 0.01

Search radius in miles for geo-distance filtering (requires latitude and longitude, e.g. 25)

date-from

string

Status date range start (ISO 8601, e.g. 2024-01-01)

date-to

string

Status date range end (ISO 8601, e.g. 2024-12-31)

limit

number · min: 1 · max: 1000

Number of records to return per page. Minimum 1, maximum 1000. Default 10.

sort-by

string · enum

Sort field. Defaults to relevance for full-text queries; otherwise to most-recent-issued.

Enum values:

city

address

jurisdiction

county

state

sort-order

string · enum

Sort direction

Enum values:

asc

desc

details

number · min: 0 · max: 1

Include permit details in the response. Use 0 for count-only results and 1 for full results. Default 1.

next-page-id

string

Cursor token for the pagination (from previous response next-page-id field)

Search permits › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Search permits › Responses

200

Search results

PermitSearchResultDto

Permit[] · required

total

number · required

Total number of records matching the query, across all pages

limit

number · required

Number of records returned in this response

totalPages

number · required

Total number of pages available at the current limit

next_page_id

string · required

Cursor token for the pagination

GET/v1/permits/search

curl --request GET \
  --url https://api.mykukun.com/v1/permits/search \
  --header 'Authorization: <string>'

Example Responses

{
  "success": true,
  "message": {
    "permits": [
      {
        "permit": {
          "id": "MNDU000085656",
          "number": null,
          "description": null,
          "status": "applied",
          "labels": "",
          "tags": [
            "kitchen-remodel"
          ],
          "type": "residential",
          "city_assigned_cost": null,
          "fees": null,
          "inspection_pass_rate": null,
          "timeline": [
            {
              "status": "applied",
              "date": "2015-11-10"
            },
            {
              "status": "issued",
              "date": "2015-11-12"
            },
            {
              "status": "closed",
              "date": "2025-05-27"
            }
          ],
          "durations": {
            "total_days": 0,
            "construction_days": null,
            "approval_days": null
          }
        },
        "location": {
          "address": {
            "street_address": null,
            "city": "Duluth",
            "county": "St. Louis",
            "state": "Minnesota",
            "zip_code": "55806",
            "zip_plus4": "5315"
          },
          "coordinates": {
            "lat": null,
            "lng": null
          },
          "postal_metadata": {
            "delivery_point_barcode": "558115315213"
          },
          "jurisdiction": []
        }
      }
    ],
    "total": 139,
    "limit": 1,
    "totalPages": 139,
    "next_page_id": "WzAsIk1ORFUwMDAwODEwOTQiXQ=="
  },
  "errors": null,
  "metadata": {
    "responseId": "8e4b43ff9b47ae09cac2b9d428376bea",
    "timestamp": "2026-05-27T10:53:30.307Z",
    "version": "v1"
  }
}

json

application/json

Search addresses by permit condition in an area

GET

https://api.mykukun.com

/v1/permits/area-search

Returns deduplicated addresses that either have or are missing a permit label within a date window. Use label-condition=has for addresses with matching permits, or label-condition=missing for addresses without matching permits.

Search addresses by permit condition in an area › query Parameters

label

string · maxLength: 100 · required

Permit label to check

label-condition

string · enum · required

has = address has matching permit, missing = address has no matching permit

Enum values:

has

missing

date-from

string · required

Start date for permit check window (ISO 8601)

date-to

string · required

End date for permit check window (ISO 8601)

zip-code

string · maxLength: 10

Area filter by ZIP code

city

string · maxLength: 200

Area filter by city

county

string · maxLength: 200

Area filter by county

state

string · maxLength: 200

Area filter by state

latitude

number · min: -90 · max: 90

Center latitude for radius-based area search (requires longitude and distance)

longitude

number · min: -180 · max: 180

Center longitude for radius-based area search (requires latitude and distance)

distance

number · min: 0.01

Radius distance in miles (required when latitude/longitude are provided)

limit

number · min: 1 · max: 1000

Page size (max 1000, default 50)

next-page-id

string

Cursor token for pagination (from previous response next_page_id field)

details

number · enum

Include details in response. 0 = count-only, 1 = full results

Enum values:

Search addresses by permit condition in an area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Search addresses by permit condition in an area › Responses

200

Area search results

AreaSearchResultDto

AreaSearchAddressResultDto[] · required

total

number · required

Total number of addresses matching the query

limit

number · required

Number of results per page

totalPages

number · required

Total pages based on total and limit

next_page_id

string | null · required

Cursor token for the next page. Null if there are no more results.

GET/v1/permits/area-search

curl --request GET \
  --url 'https://api.mykukun.com/v1/permits/area-search?label=%3Cstring%3E&label-condition=%3Cstring%3E&date-from=%3Cstring%3E&date-to=%3Cstring%3E' \
  --header 'Authorization: <string>'

Example Responses

{
  "addresses": [
    {
      "address": {
        "street_address": "street_address",
        "city": "city",
        "county": "county",
        "state": "state",
        "zip_code": "zip_code",
        "zip_plus4": "zip_plus4"
      },
      "coordinates": {
        "lat": 0,
        "lng": 0
      },
      "permit_check": {
        "label": "label",
        "label_condition": "has",
        "date_from": "date_from",
        "date_to": "date_to",
        "matches": [
          {
            "id": "id",
            "number": "number",
            "description": "description",
            "status": "status",
            "date": "date"
          }
        ]
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "totalPages": 0,
  "next_page_id": "next_page_id"
}

json

application/json

Search permits

GET

https://api.mykukun.com

/v1/permits/search

Search permits › query Parameters

status

string · enum

Permit status filter. Use lowercase kebab-case values only.

Enum values:

applied

issued

in-process

denied

closed

review

expired

inspection

label

string

address

string · maxLength: 500

Street address filter (flexible AND match, e.g. 2601 Leaning Pine Ln)

city

string · maxLength: 200

City name filter (exact match, case-insensitive). Example: Tampa.

state

string · maxLength: 200

State name filter (exact match, e.g. Florida)

zip-code

string · maxLength: 10

ZIP code filter (exact match, e.g. 33565)

county

string · maxLength: 200

County name filter (exact match, e.g. Hillsborough)

jurisdiction

string · maxLength: 200

Issuing jurisdiction — matched against both city and county fields (e.g. Los Angeles)

latitude

number · min: -90 · max: 90

Center point latitude for geo-distance filtering. Requires longitude and distance. Example: 28.0614426.

longitude

number · min: -180 · max: 180

Center point longitude for geo-distance filtering. Requires latitude and distance. Example: -82.150608.

distance

number · min: 0.01

Search radius in miles for geo-distance filtering (requires latitude and longitude, e.g. 25)

date-from

string

Status date range start (ISO 8601, e.g. 2024-01-01)

date-to

string

Status date range end (ISO 8601, e.g. 2024-12-31)

limit

number · min: 1 · max: 1000

Number of records to return per page. Minimum 1, maximum 1000. Default 10.

sort-by

string · enum

Sort field. Defaults to relevance for full-text queries; otherwise to most-recent-issued.

Enum values:

city

address

jurisdiction

county

state

sort-order

string · enum

Sort direction

Enum values:

asc

desc

details

number · min: 0 · max: 1

Include permit details in the response. Use 0 for count-only results and 1 for full results. Default 1.

next-page-id

string

Cursor token for the pagination (from previous response next-page-id field)

Search permits › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Search permits › Responses

200

Search results

PermitSearchResultDto

Permit[] · required

total

number · required

Total number of records matching the query, across all pages

limit

number · required

Number of records returned in this response

totalPages

number · required

Total number of pages available at the current limit

next_page_id

string · required

Cursor token for the pagination

Search addresses by permit condition in an area

GET

https://api.mykukun.com

/v1/permits/area-search

Search addresses by permit condition in an area › query Parameters

label

string · maxLength: 100 · required

Permit label to check

label-condition

string · enum · required

has = address has matching permit, missing = address has no matching permit

Enum values:

has

missing

date-from

string · required

Start date for permit check window (ISO 8601)

date-to

string · required

End date for permit check window (ISO 8601)

zip-code

string · maxLength: 10

Area filter by ZIP code

city

string · maxLength: 200

Area filter by city

county

string · maxLength: 200

Area filter by county

state

string · maxLength: 200

Area filter by state

latitude

number · min: -90 · max: 90

Center latitude for radius-based area search (requires longitude and distance)

longitude

number · min: -180 · max: 180

Center longitude for radius-based area search (requires latitude and distance)

distance

number · min: 0.01

Radius distance in miles (required when latitude/longitude are provided)

limit

number · min: 1 · max: 1000

Page size (max 1000, default 50)

next-page-id

string

Cursor token for pagination (from previous response next_page_id field)

details

number · enum

Include details in response. 0 = count-only, 1 = full results

Enum values:

Search addresses by permit condition in an area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Search addresses by permit condition in an area › Responses

200

Area search results

AreaSearchResultDto

AreaSearchAddressResultDto[] · required

total

number · required

Total number of addresses matching the query

limit

number · required

Number of results per page

totalPages

number · required

Total pages based on total and limit

next_page_id

string | null · required

Cursor token for the next page. Null if there are no more results.