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 — and they only work if those places are on your plan. A one-state subscription cannot search the other two.
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,
"inOpportunityZone": true,
"inFemaFloodZone": false,
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"landUses": [
{
"type": "residential",
"typeLabel": "Residential",
"subtype": "multifamily",
"subtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"matchedOn": []
}
],
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions"
}
],
"meta": {
"schemaVersion": "2026-09-16",
"representation": "compact",
"total": 1,
"pageCount": 1,
"hasMore": true,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 298,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
1,
57,
54
],
"propertyTypes": [
"residential"
]
},
"appliedDefaults": [
"taxonomyMatchMode=primary_only",
"includeGovernmentDecisions=false",
"leadTypes=private",
"dateRange=last_1_year",
"sort=meetingDate",
"order=desc"
],
"resolvedFrom": {
"states": [
{
"input": "UT",
"id": 1
},
{
"input": "CO",
"id": 57
},
{
"input": "AZ",
"id": 54
}
]
},
"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": null,
"matchCountIsExact": false,
"matchCountBasis": "not_computed",
"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 its numeric state id 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 replaces the state scope — it neither adds to the states you named nor intersects with them, so those states are not searched in full. The response discloses it with a geography_narrowed_to_smallest_scope warning in meta.warnings. Watch this with ids: a cityIds value that sits outside the states you also sent still wins, and you will be billed for the records it returns — check meta.appliedFilters before you page. 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
],
"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"
],
"inOpportunityZone": true,
"inFemaFloodZone": false,
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"leadType": "private",
"leadTypeLabel": "Private",
"stage": "entitlement",
"stageLabel": "Entitlement",
"landUses": [
{
"type": "residential",
"typeLabel": "Residential",
"subtype": "multifamily",
"subtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"matchedOn": []
}
],
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions",
"statusSummary": "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,
"squareFootage": null,
"unitMix": [
{
"count": 240,
"type": "apartment",
"typeLabel": "Apartment"
}
],
"totalUnitCount": 240,
"bedroomCount": null,
"buildingStories": null,
"floorCount": null,
"buildingHeightFeet": null,
"parkingSpaces": 372,
"existingZoning": "A-1",
"proposedZoning": "RM-16",
"isRezone": true,
"constructionType": "new_building",
"constructionTypeLabel": "New Building",
"projectSize": null,
"projectSizeLabel": null,
"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",
"emailSource": "filing",
"phone": "+1-555-0142",
"phoneSource": "filing",
"linkedinUrl": 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"
},
"companyEnrichment": [],
"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.",
"summary": "A 240-unit garden-style apartment community on 9.8 acres.",
"voteSummary": {
"yes": 2,
"no": 1,
"abstain": 0,
"absent": 1,
"total": 4,
"isUnanimous": false,
"meetingDate": "2026-06-17"
},
"sourceDocumentUrl": "https://www.example-city.gov/media/agendas/2026-06-17-planning-commission-packet.pdf"
}
],
"meta": {
"schemaVersion": "2026-09-16",
"representation": "standard",
"total": 1,
"pageCount": 1,
"hasMore": true,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 297,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
1
],
"cities": [
31688
]
},
"appliedDefaults": [
"taxonomyMatchMode=primary_only",
"includeGovernmentDecisions=false",
"leadTypes=private",
"dateRange=last_1_year",
"sort=meetingDate",
"order=desc"
],
"resolvedFrom": {
"states": [
{
"input": "UT",
"id": 1
}
],
"cities": [
{
"input": "West Valley City",
"id": 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": null,
"matchCountIsExact": false,
"matchCountBasis": "not_computed",
"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.
Which states this key can search
curl 'https://api.boardwalkai.com/api/v1/locations/states' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": [
{
"id": 54,
"name": "Arizona",
"abbreviation": "AZ",
"latitude": 34.0489,
"longitude": -111.0937,
"entitled": false
},
{
"id": 57,
"name": "Colorado",
"abbreviation": "CO",
"latitude": 39.5501,
"longitude": -105.7821,
"entitled": false
},
{
"id": 1,
"name": "Utah",
"abbreviation": "UT",
"latitude": 39.321,
"longitude": -111.0937,
"entitled": true
}
],
"meta": {
"geographyScope": "states",
"entitledStateIds": [
1
],
"countyRestricted": false
}
}The response shape on this page is the one the endpoint builds — the keys, their nesting and their types are asserted against the shipping code by a test. The numbers inside it are the scenario being walked through, not a measurement of the corpus.
The default nobody expects
What it costs
Adding a geography filter does not add a surcharge. On County, State, and National, searching those records is free. Narrowing the geography just makes the set smaller and easier to work with. On API Only and the trial, each new record costs 1 credit, so a tighter geography also lowers the bill.
| Records delivered | County / State / National | Trial or API Only |
|---|---|---|
| 100 | 0 | 100 |
| 1,000 | 0 | 1,000 |
| 10,000 | 0 | 10,000 |
Next
Ready to make a call?
A free Boardwalk trial includes API access, 50 record-export credits (search, CSV, MCP), and 5 Find Contact Info lookups. Counting, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.