Targeting a geography
An exact list of states, a single county, a single city — and how to prove the API searched what you meant.
Who this is for
Homebuilders and lead-gen teams whose market is a specific list of places, not a region. "Utah, Colorado and Arizona" and "just West Valley City" are both first-class queries.
A list of states
Pass every state you want. Values inside one parameter are an OR; different parameters are ANDed. States accept numeric ids, USPS abbreviations, or full names — use whichever your data already holds.
An exact list of states
curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT%2CCO%2CAZ&propertyTypes=residential&representation=compact&limit=1' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": [
{
"id": 184203,
"recordType": "project",
"projectName": "Alta Ridge Phase II",
"boardwalkLink": "https://boardwalkai.com/map/#project=184203",
"mergedFrom": [
184203,
184987
],
"lastUpdated": "2026-06-18T09:22:41Z",
"meetingDate": "2026-06-17",
"delivery": {
"alreadyExported": false,
"updatedSinceExport": null,
"lastExportedAt": null,
"billed": true
},
"address": "3600 S Constitution Blvd, West Valley City, UT",
"city": "West Valley City",
"county": "Salt Lake",
"state": "UT",
"latitude": 40.6916,
"longitude": -112.0011,
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions"
}
],
"meta": {
"schemaVersion": "2026-08-02",
"representation": "compact",
"total": 1,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 298,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
44,
6,
3
],
"propertyTypes": [
"residential"
]
},
"appliedDefaults": [
"dateRange=last_1_year"
],
"resolvedFrom": {
"states": {
"UT": 44,
"CO": 6,
"AZ": 3
}
},
"warnings": [
{
"code": "default_date_window_applied",
"message": "No date filter was given, so the last 12 months of meetings were searched — the same window the product shows. Pass dateRange=all to search everything.",
"params": [
"meetingDateFrom"
]
},
{
"code": "filter_evidence_unconfirmed",
"message": "These filters currently match our full index. A returned record with a null value for the attribute you filtered on is a record we could not confirm.",
"params": [
"propertyTypes"
]
}
],
"matchCount": 3140,
"matchCountIsExact": true,
"duplicatesCollapsed": 0,
"collapseApplied": true,
"delivery": {
"mode": "all",
"notPreviouslyExported": 1,
"previouslyExported": 0,
"updatedSinceExport": 0,
"billed": 1,
"notRebilled": 0,
"ledgerApplied": true
}
}
}Record bodies on this page were produced by running Boardwalk's production response mapper over a documented sample project, so the field set, the labels and the empty fields are exactly what the API emits. The project itself is a sample, not a real filing.
Two things in that response are worth reading before the records. meta.appliedFilters is the receipt: it shows what actually ran after normalisation, so "UT" resolving to state id 44 is visible rather than assumed. meta.resolvedFrom shows the mapping it used. If you ever wonder whether the API searched what you meant, these two fields answer it without a support ticket.
One city
A city or county narrows within the states you named — it does not add to them. Names are resolved against the state when you give one, and an ambiguous name is an error rather than a silently wider search: there are Springfields in more than one state, and guessing would cost you credits on the wrong market.
One city, resolved by name
curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT&cities=West%20Valley%20City&limit=1' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": [
{
"id": 184203,
"recordType": "project",
"projectName": "Alta Ridge Phase II",
"projectHeadline": "Planning Commission approved 240 apartments with conditions",
"boardwalkLink": "https://boardwalkai.com/map/#project=184203",
"mergedFrom": [
184203,
184987
],
"createdAt": "2026-05-04T00:00:00Z",
"lastUpdated": "2026-06-18T09:22:41Z",
"meetingDate": "2026-06-17",
"delivery": {
"alreadyExported": false,
"updatedSinceExport": null,
"lastExportedAt": null,
"billed": true
},
"address": "3600 S Constitution Blvd, West Valley City, UT",
"city": "West Valley City",
"county": "Salt Lake",
"state": "UT",
"postalCode": "84119",
"latitude": 40.6916,
"longitude": -112.0011,
"locationPrecision": "address",
"locationPrecisionLabel": "Address",
"isApproximate": false,
"parcelApn": [
"15-27-301-004"
],
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions",
"statusDetail": "The commission approved the preliminary plat subject to eight conditions.",
"requestType": "final_plat",
"requestTypeLabel": "Final Plat",
"decisionBody": "Planning Commission",
"caseNumbers": [
"PLAT-2026-0142"
],
"acreage": 9.8,
"unitCount": [
{
"count": 240,
"type": "apartment",
"typeLabel": "Apartment"
}
],
"totalUnitCount": 240,
"existingZoning": "A-1",
"proposedZoning": "RM-16",
"isRezone": true,
"constructionType": "new_building",
"constructionTypeLabel": "New Building",
"ownerType": "private",
"ownerTypeLabel": "Private",
"constructionDescription": "A 240-unit garden-style apartment community on 9.8 acres.",
"developerCompany": "Alta Ridge Development LLC",
"developerCompanyRole": "developer",
"developerCompanyRoleLabel": "Developer",
"contacts": [
{
"name": "Rachel Okafor",
"title": "Director of Development",
"role": "developer",
"roleLabel": "Developer",
"partyClass": "external",
"partyClassLabel": "External Party",
"entityType": "person",
"company": "Alta Ridge Development LLC",
"email": "r.okafor@example.com",
"emailConfidence": "high",
"emailSource": "filing",
"phone": "+1-555-0142",
"phoneConfidence": "high",
"phoneSource": "filing",
"linkedinUrl": null,
"linkedinConfidence": null,
"linkedinSource": null,
"contactProvenance": "filing",
"enrichmentSource": null,
"enrichedAt": null,
"enrichmentStatus": "not_requested",
"contactsWithheldReason": null
}
],
"contactEnrichment": {
"status": "not_requested",
"statusLabel": "Not Requested",
"attemptedAt": null,
"contactsFound": 0,
"source": "registry"
},
"publicOfficials": [
{
"name": "Dana Whitfield",
"title": "Senior Planner",
"role": "city_planner",
"roleLabel": "City Planner",
"partyClass": "government",
"organization": "West Valley City"
}
],
"contactSummary": {
"externalCount": 1,
"governmentCount": 1,
"unclassifiedCount": 0,
"withEmail": 1,
"withPhone": 1,
"withLinkedin": 0,
"enrichedCount": 0,
"lowConfidenceWithheld": 0,
"withheldCount": 0,
"withheldReason": null
},
"keyFacts": [
{
"fact": "240 apartment units across six buildings",
"category": "unit_mix",
"categoryLabel": "Unit Mix"
}
],
"evidence": "Commissioner Reyes moved to approve subject to conditions 1-8.",
"voteSummary": {
"yes": 2,
"no": 1,
"abstain": 0,
"absent": 1,
"total": 4,
"isUnanimous": false,
"meetingDate": "2026-06-17"
}
}
],
"meta": {
"schemaVersion": "2026-08-02",
"representation": "standard",
"total": 1,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 297,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
44
],
"cities": [
31688
]
},
"appliedDefaults": [
"dateRange=last_1_year"
],
"resolvedFrom": {
"states": {
"UT": 44
},
"cities": {
"West Valley City": 31688
}
},
"warnings": [
{
"code": "default_date_window_applied",
"message": "No date filter was given, so the last 12 months of meetings were searched — the same window the product shows. Pass dateRange=all to search everything.",
"params": [
"meetingDateFrom"
]
}
],
"matchCount": 96,
"matchCountIsExact": true,
"duplicatesCollapsed": 0,
"collapseApplied": true,
"delivery": {
"mode": "all",
"notPreviouslyExported": 1,
"previouslyExported": 0,
"updatedSinceExport": 0,
"billed": 1,
"notRebilled": 0,
"ledgerApplied": true
}
}
}Record bodies on this page were produced by running Boardwalk's production response mapper over a documented sample project, so the field set, the labels and the empty fields are exactly what the API emits. The project itself is a sample, not a real filing.
Finding the ids
The whole location tree is free. Nothing on /locations/* costs a credit, so building a local mapping of ids is a zero-cost operation you can run on every deploy.
List the states you can filter by
curl 'https://api.boardwalkai.com/api/v1/locations/states' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": [
{
"id": 44,
"name": "Utah",
"abbreviation": "UT",
"projectCount": 41822
},
{
"id": 6,
"name": "Colorado",
"abbreviation": "CO",
"projectCount": 18304
},
{
"id": 3,
"name": "Arizona",
"abbreviation": "AZ",
"projectCount": 15977
}
],
"meta": {
"count": 3
}
}We were not able to execute this call while writing the page, so treat the body as indicative of the shape rather than as a captured response. If it disagrees with what you receive, what you receive is correct — please tell us.
The default nobody expects
What it costs
Geography is a filter, and filters are free. You pay for the records the filtered query delivers, at 1 credit each. Narrowing the geography is therefore the cheapest way to reduce a bill.
| Records delivered | Credits |
|---|---|
| 100 | 100 |
| 1,000 | 1,000 |
| 10,000 | 10,000 |
Next
Ready to make a call?
A free Boardwalk trial includes API access and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.