Cities - Core Projects - Constructora AyC

Overview

The Cities API (Ciudades) allows you to manage city records in the system. Cities are the lowest level of the geographic hierarchy: Country → State → City. Cities can have postal codes and are linked to locations (Ubicaciones) within the Core Projects system.

Model Structure

Table: ciudades Primary Key: id_ciudad

Fields

id_ciudad

integer

Unique identifier for the city

nombre

string

required

City name (max 120 characters)

codigo_postal

string

Postal/ZIP code for the city (max 20 characters)

id_departamento

integer

required

Foreign key reference to the parent state/department

created_at

timestamp

Record creation timestamp

updated_at

timestamp

Record last update timestamp

Relationships

departamento

object

The parent state/department object with nested country data

ubicaciones

array

Collection of locations (project sites) within this city

List All Cities

curl --request GET \
  --url https://api.coreprojects.com/api/ciudades \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "data": [
    {
      "id_ciudad": 1,
      "nombre": "Bogotá",
      "codigo_postal": "110111",
      "id_departamento": 1,
      "created_at": "2024-01-15T10:40:00.000000Z",
      "updated_at": "2024-01-15T10:40:00.000000Z",
      "departamento": {
        "id_departamento": 1,
        "nombre": "Cundinamarca",
        "id_pais": 1,
        "created_at": "2024-01-15T10:35:00.000000Z",
        "updated_at": "2024-01-15T10:35:00.000000Z",
        "pais": {
          "id_pais": 1,
          "nombre": "Colombia",
          "created_at": "2024-01-15T10:30:00.000000Z",
          "updated_at": "2024-01-15T10:30:00.000000Z"
        }
      },
      "ubicaciones": []
    },
    {
      "id_ciudad": 2,
      "nombre": "Medellín",
      "codigo_postal": "050001",
      "id_departamento": 2,
      "created_at": "2024-01-15T11:05:00.000000Z",
      "updated_at": "2024-01-15T11:05:00.000000Z",
      "departamento": {
        "id_departamento": 2,
        "nombre": "Antioquia",
        "id_pais": 1,
        "created_at": "2024-01-15T11:00:00.000000Z",
        "updated_at": "2024-01-15T11:00:00.000000Z",
        "pais": {
          "id_pais": 1,
          "nombre": "Colombia",
          "created_at": "2024-01-15T10:30:00.000000Z",
          "updated_at": "2024-01-15T10:30:00.000000Z"
        }
      },
      "ubicaciones": []
    }
  ]
}

Endpoint

GET /api/ciudades

Response Fields

success

boolean

Indicates if the request was successful

data

array

Array of city objects with nested department, country, and locations data

Get Single City

curl --request GET \
  --url https://api.coreprojects.com/api/ciudades/1 \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "data": {
    "id_ciudad": 1,
    "nombre": "Bogotá",
    "codigo_postal": "110111",
    "id_departamento": 1,
    "created_at": "2024-01-15T10:40:00.000000Z",
    "updated_at": "2024-01-15T10:40:00.000000Z",
    "departamento": {
      "id_departamento": 1,
      "nombre": "Cundinamarca",
      "id_pais": 1,
      "created_at": "2024-01-15T10:35:00.000000Z",
      "updated_at": "2024-01-15T10:35:00.000000Z",
      "pais": {
        "id_pais": 1,
        "nombre": "Colombia",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    },
    "ubicaciones": [
      {
        "id_ubicacion": 1,
        "direccion": "Calle 100 #15-20",
        "barrio": "Chicó Norte",
        "id_ciudad": 1,
        "created_at": "2024-01-15T12:00:00.000000Z",
        "updated_at": "2024-01-15T12:00:00.000000Z"
      }
    ]
  }
}

Endpoint

GET /api/ciudades/{id}

Path Parameters

integer

required

The unique identifier of the city

Create City

curl --request POST \
  --url https://api.coreprojects.com/api/ciudades \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Bogotá",
    "codigo_postal": "110111",
    "id_departamento": 1
  }'

{
  "success": true,
  "message": "Ciudad creada exitosamente",
  "data": {
    "id_ciudad": 1,
    "nombre": "Bogotá",
    "codigo_postal": "110111",
    "id_departamento": 1,
    "created_at": "2024-01-15T10:40:00.000000Z",
    "updated_at": "2024-01-15T10:40:00.000000Z",
    "departamento": {
      "id_departamento": 1,
      "nombre": "Cundinamarca",
      "id_pais": 1,
      "created_at": "2024-01-15T10:35:00.000000Z",
      "updated_at": "2024-01-15T10:35:00.000000Z",
      "pais": {
        "id_pais": 1,
        "nombre": "Colombia",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    }
  }
}

Endpoint

POST /api/ciudades

Body Parameters

nombre

string

required

Name of the city (max 120 characters)

codigo_postal

string

Postal/ZIP code for the city (max 20 characters)

id_departamento

integer

required

ID of the parent state/department (must exist in the departamentos table)

Validation Rules

nombre: Required, string, maximum 120 characters
codigo_postal: Optional, string, maximum 20 characters
id_departamento: Required, must exist in the departamento table

Update City

curl --request PUT \
  --url https://api.coreprojects.com/api/ciudades/1 \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Bogotá D.C.",
    "codigo_postal": "110111",
    "id_departamento": 1
  }'

{
  "success": true,
  "message": "Ciudad actualizada exitosamente",
  "data": {
    "id_ciudad": 1,
    "nombre": "Bogotá D.C.",
    "codigo_postal": "110111",
    "id_departamento": 1,
    "created_at": "2024-01-15T10:40:00.000000Z",
    "updated_at": "2024-01-15T14:20:00.000000Z",
    "departamento": {
      "id_departamento": 1,
      "nombre": "Cundinamarca",
      "id_pais": 1,
      "created_at": "2024-01-15T10:35:00.000000Z",
      "updated_at": "2024-01-15T10:35:00.000000Z",
      "pais": {
        "id_pais": 1,
        "nombre": "Colombia",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    }
  }
}

Endpoint

PUT /api/ciudades/{id}

Path Parameters

integer

required

The unique identifier of the city to update

Body Parameters

nombre

string

required

Updated name of the city (max 120 characters)

codigo_postal

string

Updated postal/ZIP code (max 20 characters)

id_departamento

integer

required

Updated parent state/department ID (must exist in the departamentos table)

Delete City

curl --request DELETE \
  --url https://api.coreprojects.com/api/ciudades/1 \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "message": "Ciudad eliminada exitosamente"
}

Endpoint

DELETE /api/ciudades/{id}

Path Parameters

integer

required

The unique identifier of the city to delete

Business Rules

A city cannot be deleted if it has associated locations (Ubicaciones). You must first delete all locations before deleting the city.

Get Cities by State

curl --request GET \
  --url https://api.coreprojects.com/api/departamentos/1/ciudades \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "data": [
    {
      "id_ciudad": 1,
      "nombre": "Bogotá",
      "codigo_postal": "110111",
      "id_departamento": 1,
      "created_at": "2024-01-15T10:40:00.000000Z",
      "updated_at": "2024-01-15T10:40:00.000000Z",
      "ubicaciones": [
        {
          "id_ubicacion": 1,
          "direccion": "Calle 100 #15-20",
          "barrio": "Chicó Norte",
          "id_ciudad": 1,
          "created_at": "2024-01-15T12:00:00.000000Z",
          "updated_at": "2024-01-15T12:00:00.000000Z"
        }
      ]
    },
    {
      "id_ciudad": 3,
      "nombre": "Chía",
      "codigo_postal": "250001",
      "id_departamento": 1,
      "created_at": "2024-01-15T11:30:00.000000Z",
      "updated_at": "2024-01-15T11:30:00.000000Z",
      "ubicaciones": []
    }
  ]
}

Endpoint

GET /api/departamentos/{id_departamento}/ciudades

Path Parameters

id_departamento

integer

required

The unique identifier of the state/department

Description

Retrieve all cities that belong to a specific state/department. Each city includes its associated locations.

Get Cities by Postal Code

curl --request GET \
  --url https://api.coreprojects.com/api/ciudades/codigo-postal/110111 \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "data": [
    {
      "id_ciudad": 1,
      "nombre": "Bogotá",
      "codigo_postal": "110111",
      "id_departamento": 1,
      "created_at": "2024-01-15T10:40:00.000000Z",
      "updated_at": "2024-01-15T10:40:00.000000Z",
      "departamento": {
        "id_departamento": 1,
        "nombre": "Cundinamarca",
        "id_pais": 1,
        "created_at": "2024-01-15T10:35:00.000000Z",
        "updated_at": "2024-01-15T10:35:00.000000Z",
        "pais": {
          "id_pais": 1,
          "nombre": "Colombia",
          "created_at": "2024-01-15T10:30:00.000000Z",
          "updated_at": "2024-01-15T10:30:00.000000Z"
        }
      }
    }
  ]
}

Endpoint

GET /api/ciudades/codigo-postal/{codigo_postal}

Path Parameters

codigo_postal

string

required

The postal/ZIP code to search for

Description

Search for cities by their postal code. This endpoint returns all cities that match the provided postal code, including full department and country information.

Relationships

Parent Relationship

State/Department (Departamento): Each city belongs to one state/department. See the States API for state management.
Country (País): Through the state relationship, each city is indirectly associated with a country.

Child Relationships

Locations (Ubicaciones): Each city can have multiple project locations. Use the following endpoint to get locations for a specific city:

GET /api/ciudades/{id_ciudad}/ubicaciones

Projects (Proyectos): Projects can be filtered by city:

GET /api/ciudades/{id_ciudad}/proyectos

Geographic Hierarchy

The complete geographic hierarchy in Core Projects is:

Country (País) → Countries API
State/Department (Departamento) → States API
City (Ciudad) → Current API
Location (Ubicación) → Locations API

This hierarchy ensures proper organization of construction projects across different geographic regions.

Overview

Geographic Data

Projects & Properties

Sales & Clients

Organization

​Overview

​Model Structure

​Fields

​Relationships

​List All Cities

​Endpoint

​Response Fields

​Get Single City

​Endpoint

​Path Parameters

​Create City

​Endpoint

​Body Parameters

​Validation Rules

​Update City

​Endpoint

​Path Parameters

​Body Parameters

​Delete City

​Endpoint

​Path Parameters

​Business Rules

​Get Cities by State

​Endpoint

​Path Parameters

​Description

​Get Cities by Postal Code

​Endpoint

​Path Parameters

​Description

​Relationships

​Parent Relationship

​Child Relationships

​Geographic Hierarchy

Build docs developers (and LLMs) love

Overview

Model Structure

Fields

Relationships

List All Cities

Endpoint

Response Fields

Get Single City

Endpoint

Path Parameters

Create City

Endpoint

Body Parameters

Validation Rules

Update City

Endpoint

Path Parameters

Body Parameters

Delete City

Endpoint

Path Parameters

Business Rules

Get Cities by State

Endpoint

Path Parameters

Description

Get Cities by Postal Code

Endpoint

Path Parameters

Description

Relationships

Parent Relationship

Child Relationships

Geographic Hierarchy