Ciudades API - RestAPI

Overview

The Ciudades (Cities) API manages city records with geographic location data stored as JSON for Google Maps integration.

Model Structure

The Ciudad model represents cities with country associations and Google Maps location data.

Fields

id_ciudad

integer

required

Primary key. Auto-incremented unique identifier for the city.

id_pais

integer

required

Foreign key reference to the Pais (Country) model. Links the city to its country.

nombre

string

required

City name. Maximum 80 characters.

ubicacion_google_maps

object

required

JSON field containing Google Maps location data. Stores latitude, longitude, and optional place information.Default: {}

Endpoints

List Cities

GET /api/ciudades/

Retrieves all cities in the system.

Query Parameters

id_pais

integer

Optional. Filter cities by country ID.

Response

id_ciudad

integer

Unique identifier for the city

id_pais

integer

ID of the country this city belongs to

nombre

string

Name of the city

ubicacion_google_maps

object

Google Maps location data including coordinates

ubicacion_google_maps.lat

number

Latitude coordinate

ubicacion_google_maps.lng

number

Longitude coordinate

ubicacion_google_maps.place_id

string

Google Maps Place ID (optional)

ubicacion_google_maps.formatted_address

string

Formatted address string (optional)

Example Response

[
  {
    "id_ciudad": 1,
    "id_pais": 1,
    "nombre": "Quito",
    "ubicacion_google_maps": {
      "lat": -0.1806532,
      "lng": -78.4678382,
      "place_id": "ChIJUdXT06dBJZERcrgUJ3nTs_E",
      "formatted_address": "Quito, Ecuador"
    }
  },
  {
    "id_ciudad": 2,
    "id_pais": 1,
    "nombre": "Guayaquil",
    "ubicacion_google_maps": {
      "lat": -2.1709979,
      "lng": -79.9223592,
      "place_id": "ChIJDY7kWmWLLZAR8RiDZ1bx5cg",
      "formatted_address": "Guayaquil, Ecuador"
    }
  }
]

Get City

GET /api/ciudades/{id_ciudad}/

Retrieves a specific city by ID.

Path Parameters

id_ciudad

integer

required

The unique identifier of the city to retrieve

Response

id_ciudad

integer

Unique identifier for the city

id_pais

integer

ID of the country this city belongs to

nombre

string

Name of the city

ubicacion_google_maps

object

Google Maps location data

Example Response

{
  "id_ciudad": 1,
  "id_pais": 1,
  "nombre": "Quito",
  "ubicacion_google_maps": {
    "lat": -0.1806532,
    "lng": -78.4678382,
    "place_id": "ChIJUdXT06dBJZERcrgUJ3nTs_E",
    "formatted_address": "Quito, Ecuador"
  }
}

Create City

POST /api/ciudades/

Creates a new city with location data.

Request Body

id_pais

integer

required

ID of the country this city belongs to

nombre

string

required

Name of the city. Maximum 80 characters.

ubicacion_google_maps

object

Google Maps location data. If not provided, defaults to empty object {}.

ubicacion_google_maps.lat

number

required

Latitude coordinate

ubicacion_google_maps.lng

number

required

Longitude coordinate

ubicacion_google_maps.place_id

string

Google Maps Place ID (optional)

ubicacion_google_maps.formatted_address

string

Formatted address string (optional)

Example Request

{
  "id_pais": 1,
  "nombre": "Cuenca",
  "ubicacion_google_maps": {
    "lat": -2.9001285,
    "lng": -79.0058965,
    "place_id": "ChIJ_T5g5WZis5ERzQZKz_hCAAE",
    "formatted_address": "Cuenca, Ecuador"
  }
}

Response

id_ciudad

integer

Unique identifier for the newly created city

id_pais

integer

ID of the country

nombre

string

Name of the city

ubicacion_google_maps

object

Google Maps location data

Update City

PUT /api/ciudades/{id_ciudad}/

Updates an existing city’s information.

Path Parameters

id_ciudad

integer

required

The unique identifier of the city to update

Request Body

id_pais

integer

required

ID of the country this city belongs to

nombre

string

required

Updated name of the city. Maximum 80 characters.

ubicacion_google_maps

object

Updated Google Maps location data

ubicacion_google_maps.lat

number

Latitude coordinate

ubicacion_google_maps.lng

number

Longitude coordinate

ubicacion_google_maps.place_id

string

Google Maps Place ID (optional)

ubicacion_google_maps.formatted_address

string

Formatted address string (optional)

Example Request

{
  "id_pais": 1,
  "nombre": "Quito - Distrito Metropolitano",
  "ubicacion_google_maps": {
    "lat": -0.1806532,
    "lng": -78.4678382,
    "place_id": "ChIJUdXT06dBJZERcrgUJ3nTs_E",
    "formatted_address": "Quito, Pichincha, Ecuador",
    "zoom": 12
  }
}

Partial Update City

PATCH /api/ciudades/{id_ciudad}/

Partially updates a city’s information. Only provided fields will be updated.

Path Parameters

id_ciudad

integer

required

The unique identifier of the city to update

Request Body

Any subset of the city fields can be provided.

Example Request

{
  "ubicacion_google_maps": {
    "lat": -0.1806532,
    "lng": -78.4678382,
    "zoom": 13
  }
}

Delete City

DELETE /api/ciudades/{id_ciudad}/

Deletes a city from the system.

Path Parameters

id_ciudad

integer

required

The unique identifier of the city to delete

Response

Returns 204 No Content on successful deletion.

Google Maps Location Structure

The ubicacion_google_maps field is a flexible JSON field that typically contains:

Basic Structure

{
  "lat": -0.1806532,
  "lng": -78.4678382
}

Extended Structure

{
  "lat": -0.1806532,
  "lng": -78.4678382,
  "place_id": "ChIJUdXT06dBJZERcrgUJ3nTs_E",
  "formatted_address": "Quito, Ecuador",
  "zoom": 12,
  "viewport": {
    "northeast": {
      "lat": -0.0536722,
      "lng": -78.3595432
    },
    "southwest": {
      "lat": -0.3583852,
      "lng": -78.5943072
    }
  }
}

Common Fields

lat

number

required

Latitude coordinate (decimal degrees)

lng

number

required

Longitude coordinate (decimal degrees)

place_id

string

Google Maps Place ID for precise location identification

formatted_address

string

Human-readable address string

zoom

integer

Recommended zoom level for map display (typically 10-15 for cities)

viewport

object

Bounding box for the city area

viewport.northeast

object

Northeast corner coordinates

viewport.southwest

object

Southwest corner coordinates

Relationships

The Ciudad model is referenced by:

Usuario: Users are located in specific cities
Chofer: Drivers operate in specific cities
Cliente: Clients are based in specific cities
Empresa: Companies may be registered in specific cities
CampanaPublicitaria: Campaigns target specific cities
Sector: Geographic sectors belong to cities
TallerBrandeo: Branding workshops are located in cities
RecorridoRealizado: Routes are tracked within cities
MovimientoCapital: Financial transactions are city-specific

Usage Notes

A city must belong to a valid country (Pais)
The ubicacion_google_maps field is required and should contain at minimum lat and lng coordinates
Deleting a city will cascade delete all related records
When integrating with Google Maps, use the place_id for precise location lookups
Coordinates should use WGS84 datum (standard for GPS and Google Maps)
Latitude ranges from -90 to 90, longitude from -180 to 180

Overview

Authentication & Users

Campaigns

Companies & Advertisers

Vehicles

Drivers & Clients

Campaign Operations

Financial

Workshops

Location & System

Permissions

Utilities

​Overview

​Model Structure

​Fields

​Endpoints

​List Cities

​Query Parameters

​Response

​Example Response

​Get City

​Path Parameters

​Response

​Example Response

​Create City

​Request Body

​Example Request

​Response

​Update City

​Path Parameters

​Request Body

​Example Request

​Partial Update City

​Path Parameters

​Request Body

​Example Request

​Delete City

​Path Parameters

​Response

​Google Maps Location Structure

​Basic Structure

​Extended Structure

​Common Fields

​Relationships

​Usage Notes

Build docs developers (and LLMs) love

Overview

Model Structure

Fields

Endpoints

List Cities

Query Parameters

Response

Example Response

Get City

Path Parameters

Response

Example Response

Create City

Request Body

Example Request

Response

Update City

Path Parameters

Request Body

Example Request

Partial Update City

Path Parameters

Request Body

Example Request

Delete City

Path Parameters

Response

Google Maps Location Structure

Basic Structure

Extended Structure

Common Fields

Relationships

Usage Notes