Skip to main content

​
List Cities

​
Query Parameters

​
page
integer
default:"1"
Page number (minimum: 1)
​
limit
integer
default:"10"
Items per page (minimum: 1, maximum: 100)
​
q
string
Free text search by name (case-insensitive)
​
name
string
Filter by exact name
​
countryCode
string
Filter by ISO-3166-1 alpha-2 country code (e.g., MX, CO)
​
timezone
string
Filter by IANA timezone (e.g., America/Mexico_City)
​
active
boolean
Filter by active status

​
Response

Returns a paginated list of cities with metadata.

​
Get City by ID

​
Path Parameters

​
id
string
required
City UUID

​
Response

Returns the city details including geometry if available.

​
Create City

​
Body Parameters

​
name
string
required
City name (max 120 characters)
​
countryCode
string
required
ISO-3166-1 alpha-2 country code (e.g., MX, CO)
​
timezone
string
required
Valid IANA timezone (e.g., America/Mexico_City)
​
geom
object
GeoJSON MultiPolygon representing the city boundaries
​
active
boolean
default:"true"
Whether the city is active

​
Response

​
status
string
Response status
​
data
object
The created city object

​
Error Responses

  • 409 Conflict: City already exists (name + countryCode combination)
  • 400 Bad Request: Validation error

​
Update City

​
Path Parameters

​
id
string
required
City UUID

​
Body Parameters

All parameters are optional (partial update):
​
name
string
City name (max 120 characters)
​
countryCode
string
ISO-3166-1 alpha-2 country code
​
timezone
string
Valid IANA timezone
​
geom
object
GeoJSON MultiPolygon representing the city boundaries
​
active
boolean
Whether the city is active

​
Response

Returns the updated city object.

​
Error Responses

  • 409 Conflict: Another city already exists with this name + countryCode
  • 400 Bad Request: Validation error

​
Set Active Status

​
Path Parameters

​
id
string
required
City UUID

​
Body Parameters

​
active
boolean
required
Set to true to activate, false to deactivate

​
Response

Returns the updated city with new active status.

​
Resolve City by Point

​
Query Parameters

​
lat
number
required
Latitude coordinate
​
lng
number
required
Longitude coordinate

​
Response

Returns the city containing the point, or null if no city is found.

​
Example Request

curl "https://api.rodando.com/cities/resolve/by-point?lat=19.4326&lng=-99.1332"

​
Example Response

{
  "success": true,
  "message": "City resolved",
  "data": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "Ciudad de México",
    "countryCode": "MX",
    "timezone": "America/Mexico_City",
    "active": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
If no city contains the point: 
{
  "success": true,
  "message": "No city found",
  "data": null
}

​
Use Cases

This endpoint is essential for:
  • Trip pricing - Determine which city’s pricing policies apply to a trip
  • Service availability - Check if Rodando operates in the requested location
  • Zone resolution - First step before resolving specific zones within a city
This endpoint uses PostGIS spatial queries to find the city whose geometry contains the provided point. Only active cities with defined geometries are considered.

Build docs developers (and LLMs) love

Get started for freeTalk to us