Nextdoor city slugs: the format, how to find one, and what goes wrong

Almost every empty Nextdoor run traces back to this one string. The format is simple enough to describe in a sentence and has four transformation rules underneath it, three of which only matter for cities whose names contain something other than letters.

The format

city-name--state

san-clemente--ca      San Clemente, California
dana-point--ca        Dana Point, California
saint-louis--mo       St. Louis, Missouri
fort-worth--tx        Fort Worth, Texas

Lowercase throughout, single hyphens between words in the city name, a double hyphen as the separator, then the two-letter state code. The double hyphen is what makes the format unambiguous: without it, a city called Fort Worth in a hypothetical state “TX Fort” would be unparseable.

The four transformation rules

1. Lowercase everything. No capitals survive.
2. Spaces become single hyphens. san juan capistrano → san-juan-capistrano.
3. Punctuation is dropped, not encoded. Periods, apostrophes and accents disappear rather than becoming escapes: “St. Louis” loses the period, and the abbreviation is normally spelled out.
4. The state code is mandatory. City names repeat across states — there are Springfields in more than thirty of them — so the code is not optional even when the name feels unique.

Finding a slug you are unsure about

Do not guess, and especially do not guess in a loop. Open the city page on Nextdoor in a browser and read the slug out of the URL: it costs ten seconds and removes the entire class of failure. For cities with a saint, a compass direction or an accent in the name, this is the only reliable method.

If you are working from a list of cities in a spreadsheet, verify the first three by hand and the rest will usually follow the same pattern — but verify the odd-looking ones individually rather than trusting the transformation.

What a wrong slug looks like

It does not throw. The run completes, the dataset is empty or nearly so, and the errors dataset explains why — which is exactly why failures go somewhere visible instead of being swallowed. You are not charged for rows that were never produced, so a wrong slug costs the start event and nothing else.

The three failures in order of frequency:

1. Single hyphen before the state code.
2. Punctuation left in the city name.
3. A correct slug for a city that genuinely has no businesses in the category you asked for — which is not an error at all, and is worth checking before you assume it is.

Running several cities at once

cities is an array and maxBusinessesPerCity applies per city, so ten slugs at 50 each is 500 businesses. That is the right shape for covering a metropolitan area: name the municipalities explicitly and set onlyRequestedCity: true, and you get a clean union of those cities rather than a distance-ordered blur across the region.

{
  "cities": [
    "san-clemente--ca",
    "san-juan-capistrano--ca",
    "dana-point--ca",
    "laguna-niguel--ca"
  ],
  "categories": ["Plumber", "Electrician"],
  "maxBusinessesPerCity": 60,
  "onlyRequestedCity": true
}

Letting Nextdoor pick the neighbours

If you do not know which cities surround your target, expandNearbyCities discovers them through Nextdoor's own cross-links. maxExpandedCities caps it, and that cap is not optional: Nextdoor's city graph connects the whole of the United States, so an uncapped expansion has no natural stopping point.

Expansion and onlyRequestedCity pull in opposite directions by design. Use the first when you want a trade area and the second when you want a municipality — the difference is measured here.