Cities API Endpoints: List and Retrieve Cities Data

Cities are the top-level geographical grouping in Tourify. Each city can contain many places and events, and can have one or more images attached via a polymorphic images relation. All city endpoints are publicly accessible — no authentication token is required.

List Cities

GET /api/cities Returns an alphabetically sorted array of all cities. Each city includes its associated images. Authentication: Not required.

Response — `200 OK`

Returns a JSON array. Each element has the following shape:

[].id

integer

Auto-incremented city ID.

[].name

string

The city’s name.

[].description

string | null

An optional long-form description of the city.

[].country

string

The country where the city is located.

[].images

array

Polymorphic images attached to this city via the imageable morph relation.

Show image fields

[].images[].id

integer

Image record ID.

[].images[].url

string

Publicly accessible URL of the image.

[].images[].imageable_type

string

Morph type. Value: "App\\Models\\City".

[].images[].imageable_id

integer

ID of the owning city.

[].created_at

string

ISO 8601 creation timestamp.

[].updated_at

string

ISO 8601 last-update timestamp.

Example request

curl -X GET http://localhost:8000/api/cities \
  -H "Accept: application/json"

Example response (200)

[
  {
    "id": 1,
    "name": "Barcelona",
    "description": "A vibrant city on the northeastern coast of Spain, known for its architecture and culture.",
    "country": "Spain",
    "images": [
      {
        "id": 10,
        "url": "https://example.com/images/barcelona.jpg",
        "imageable_type": "App\\Models\\City",
        "imageable_id": 1,
        "created_at": "2026-05-01T08:00:00.000000Z",
        "updated_at": "2026-05-01T08:00:00.000000Z"
      }
    ],
    "created_at": "2026-05-01T08:00:00.000000Z",
    "updated_at": "2026-05-01T08:00:00.000000Z"
  },
  {
    "id": 2,
    "name": "Madrid",
    "description": "The capital and largest city of Spain, home to world-class museums and a lively nightlife.",
    "country": "Spain",
    "images": [],
    "created_at": "2026-05-01T08:00:00.000000Z",
    "updated_at": "2026-05-01T08:00:00.000000Z"
  }
]

Get City

GET /api/cities/{city} Returns a single city by ID with all related data eager-loaded: images, places (with their images, category, and reviews), and events (with their images and associated place). Each place in the response also includes a computed average_rating field. Authentication: Not required.

Path parameters

city

integer

required

The ID of the city to retrieve.

Response — `200 OK`

integer

The city’s ID.

name

string

The city’s name.

description

string | null

An optional long-form description of the city.

country

string

The country where the city is located.

images

array

Polymorphic images attached to this city.

Show image fields

images[].id

integer

Image record ID.

images[].url

string

Publicly accessible image URL.

images[].imageable_type

string

Morph type. Value: "App\\Models\\City".

images[].imageable_id

integer

ID of the owning city.

places

array

All places that belong to this city. Each place includes its images, category, reviews, and a computed average rating.

Show place fields

places[].id

integer

Place ID.

places[].city_id

integer

FK to the parent city.

places[].category_id

integer

FK to the place’s category.

places[].name

string

Place name.

places[].description

string

Long-form place description.

places[].address

string

Street address of the place.

places[].latitude

number | null

Decimal latitude (precision: 10, scale: 7).

places[].longitude

number | null

Decimal longitude (precision: 10, scale: 7).

places[].average_rating

number | null

Computed mean of all review ratings for this place, rounded to one decimal place. null if there are no reviews.

places[].images

array

Polymorphic images attached to the place.

places[].category

object

The place’s category (id, name, description).

places[].reviews

array

All reviews submitted for this place.

events

array

All events associated with this city. Each event includes its images and the related place.

Show event fields

events[].id

integer

Event ID.

events[].city_id

integer

FK to the parent city.

events[].place_id

integer | null

FK to the associated place, if any.

events[].title

string

Event title.

events[].date

string (ISO 8601)

Date and time of the event.

events[].description

string

Event description.

events[].images

array

Polymorphic images attached to the event.

events[].place

object | null

The place where the event is held, if set.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-update timestamp.

If no city with the given {city} ID exists, Laravel returns a 404 Not Found response automatically via model binding.

Example request

curl -X GET http://localhost:8000/api/cities/1 \
  -H "Accept: application/json"

Example response (200)

{
  "id": 1,
  "name": "Barcelona",
  "description": "A vibrant city on the northeastern coast of Spain, known for its architecture and culture.",
  "country": "Spain",
  "images": [
    {
      "id": 10,
      "url": "https://example.com/images/barcelona.jpg",
      "imageable_type": "App\\Models\\City",
      "imageable_id": 1,
      "created_at": "2026-05-01T08:00:00.000000Z",
      "updated_at": "2026-05-01T08:00:00.000000Z"
    }
  ],
  "places": [
    {
      "id": 3,
      "city_id": 1,
      "category_id": 2,
      "name": "Sagrada Família",
      "description": "Antoni Gaudí's iconic unfinished basilica, a UNESCO World Heritage Site.",
      "address": "Carrer de Mallorca, 401, 08013 Barcelona",
      "latitude": 41.4036,
      "longitude": 2.1744,
      "average_rating": 4.8,
      "images": [
        {
          "id": 21,
          "url": "https://example.com/images/sagrada.jpg",
          "imageable_type": "App\\Models\\Place",
          "imageable_id": 3
        }
      ],
      "category": {
        "id": 2,
        "name": "Monuments",
        "description": "Historic monuments and landmarks."
      },
      "reviews": [
        {
          "id": 5,
          "reviewable_type": "App\\Models\\Place",
          "reviewable_id": 3,
          "user_id": 42,
          "rating": 5,
          "comment": "Absolutely breathtaking.",
          "created_at": "2026-05-10T14:22:00.000000Z"
        }
      ],
      "created_at": "2026-05-01T08:00:00.000000Z",
      "updated_at": "2026-05-01T08:00:00.000000Z"
    }
  ],
  "events": [
    {
      "id": 7,
      "city_id": 1,
      "place_id": 3,
      "title": "Gaudí Night Tour",
      "date": "2026-06-20T21:00:00.000000Z",
      "description": "A guided evening tour of Gaudí's masterpieces.",
      "images": [],
      "place": {
        "id": 3,
        "name": "Sagrada Família"
      },
      "created_at": "2026-05-02T09:00:00.000000Z",
      "updated_at": "2026-05-02T09:00:00.000000Z"
    }
  ],
  "created_at": "2026-05-01T08:00:00.000000Z",
  "updated_at": "2026-05-01T08:00:00.000000Z"
}

Overview

Endpoints

Cities API Endpoints: List and Retrieve Cities Data

List Cities

Response — `200 OK`

Get City

Path parameters

Response — `200 OK`

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​List Cities

​Response — 200 OK

​Get City

​Path parameters

​Response — 200 OK

Build docs developers (and LLMs) love

List Cities

Response — `200 OK`

Get City

Path parameters

Response — `200 OK`