listCities
List cities from the directory site to retrieve city slugs for constructing SEO-friendly search-result URLs and location-based member browsing. Supports pagination and filtering by city name, state, or country.
Instructions
List cities (location-based search & SEO slugs) - Paginated enumeration of cities enabled on this site for location-based member/post browsing and SEO page URL generation. Read-only source-of-truth for city slugs used in search-result URLs. Backed by BD's location_cities table.
Use when: resolving a human city name (e.g. "Beverly Hills") to its city_filename slug (e.g. beverly-hills) before constructing a search-result URL for a static SEO page, or discovering which cities this site has seeded.
Pagination: cursor-based (limit, page). See Rule: Pagination for full cursor/cap/stop semantics.
Filter/sort: property+property_value+property_operator, order_column+order_type. See Rule: Filter operators for the verified-working operator set, silent-drop detection, and derived-field unfilterability. Useful filters: city_ln (full name, exact match), city_filename (slug, exact), state_sn (scope to one state), country_sn (scope to one country).
Returns: { status: "success", message: [...rows] } - each row has:
locaiton_id(integer PK, BD schema typo - it islocaiton_id, NOTlocation_id; pass the typo'd form when looking up a single record)city_ln(full name)city_filename(URL slug)state_sn(2-letter state/province code; referenceslocation_states.state_sn)country_sn(2-letter country code; referenceslist_countries.country_code)
System-critical table - create & delete deliberately omitted from this MCP. Cities are managed by BD automatically (a new city row is added when a member signs up from a new location). Creating cities via API risks slug collisions with auto-created rows, and deleting risks orphaning members whose city references the row. Use updateCity only for corrections (rename, fix typo in filename). For new cities, let the next member signup seed it.
Auth: X-Api-Key header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: { "status": "error", "message": "..." } - empty-result responses return {status: "error", message: "location_cities not found", total: 0} (same ambiguous pattern as other list endpoints).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page (default 25, max 100) | |
| page | No | Pagination cursor (use next_page from previous response) | |
| property | No | Field name to filter by | |
| property_value | No | Value to filter by | |
| property_operator | No | Filter operator (word-form; symbol forms WAF-stripped). Single: eq, ne, lt, lte, gt, gte, like, not_like. CSV: in, not_in, between. Substring: contains, starts_with, ends_with (+not_). Date: year_eq, month_eq, day_eq (+not_), since_days, until_days. Length: length_eq, length_lt, length_gt, length_between. Null: is_set, is_not_set, is_null, is_not_null. See Rule: Filter operators for value shapes. | |
| order_column | No | Column to sort by | |
| order_type | No | Sort direction: ASC or DESC |