Places API Endpoints: List and Retrieve Place Data

Places are the core resource in Tourify — individual points of interest (landmarks, restaurants, museums, etc.) that belong to a city and a category. All place endpoints are publicly accessible — no authentication token is required.

List Places

GET /api/places Returns a flat array of all places, optionally filtered by city, category, or a search term. Each place includes its images, city, category, and a computed average_rating. Results are ordered by average rating descending so that the best-rated places appear first. Authentication: Not required.

Query parameters

city_id

integer

Filter results to places that belong to the city with this ID. Omit to return places from all cities.

category_id

integer

Filter results to places that belong to the category with this ID. Omit to return places from all categories.

string

Full-text search term. The API performs a case-insensitive LIKE match against the place name, address, and the name of the related city. Multiple filters can be combined — for example, city_id=1&search=park returns places in city 1 whose name, address, or city name contains “park”.

Response — `200 OK`

Returns a JSON array sorted by average_rating descending. Each element has the following shape:

[].id

integer

Auto-incremented place ID.

[].city_id

integer

FK referencing the parent city.

[].category_id

integer

FK referencing the place’s category.

[].name

string

The place name.

[].description

string

Long-form description of the place.

[].address

string

Street address of the place.

[].latitude

number | null

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

[].longitude

number | null

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

[].average_rating

number

Mean of all review ratings for the place, rounded to one decimal place. Returns 0 if there are no reviews.

[].images

array

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

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\\Place".

[].images[].imageable_id

integer

ID of the owning place.

[].city

object

The city this place belongs to.

Show city fields

[].city.id

integer

City ID.

[].city.name

string

City name.

[].city.description

string | null

City description.

[].city.country

string

Country of the city.

[].category

object

The category this place belongs to.

Show category fields

[].category.id

integer

Category ID.

[].category.name

string

Category name.

[].category.description

string | null

Category description.

[].created_at

string

ISO 8601 creation timestamp.

[].updated_at

string

ISO 8601 last-update timestamp.

Example — all places

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

Example — filter by city and category

curl -X GET "http://localhost:8000/api/places?city_id=1&category_id=2" \
  -H "Accept: application/json"

Example — search by keyword

curl -X GET "http://localhost:8000/api/places?search=park" \
  -H "Accept: application/json"

Example response (200)

[
  {
    "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.4036299,
    "longitude": 2.1743558,
    "average_rating": 4.8,
    "reviews_avg_rating": 4.8,
    "images": [
      {
        "id": 21,
        "url": "https://example.com/images/sagrada.jpg",
        "imageable_type": "App\\Models\\Place",
        "imageable_id": 3,
        "created_at": "2026-05-01T08:00:00.000000Z",
        "updated_at": "2026-05-01T08:00:00.000000Z"
      }
    ],
    "city": {
      "id": 1,
      "name": "Barcelona",
      "description": "A vibrant city on the northeastern coast of Spain.",
      "country": "Spain",
      "created_at": "2026-05-01T08:00:00.000000Z",
      "updated_at": "2026-05-01T08:00:00.000000Z"
    },
    "category": {
      "id": 2,
      "name": "Monuments",
      "description": "Historic monuments and architectural landmarks.",
      "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": 7,
    "city_id": 1,
    "category_id": 1,
    "name": "Museu Picasso",
    "description": "One of the most important collections of the artworks of Pablo Picasso.",
    "address": "Carrer de Montcada, 15-23, 08003 Barcelona",
    "latitude": 41.3851,
    "longitude": 2.1810,
    "average_rating": 4.3,
    "reviews_avg_rating": 4.3,
    "images": [],
    "city": {
      "id": 1,
      "name": "Barcelona",
      "description": "A vibrant city on the northeastern coast of Spain.",
      "country": "Spain"
    },
    "category": {
      "id": 1,
      "name": "Museums",
      "description": "Art galleries, history museums, and science centres."
    },
    "created_at": "2026-05-01T08:00:00.000000Z",
    "updated_at": "2026-05-01T08:00:00.000000Z"
  }
]

Get Place

GET /api/places/{place} Returns a single place by ID with all related data eager-loaded: images, city, category, and reviews (each review includes the author’s user object). A computed average_rating is appended to the response. Authentication: Not required.

Path parameters

place

integer

required

The ID of the place to retrieve.

Response — `200 OK`

integer

The place’s ID.

city_id

integer

FK referencing the parent city.

category_id

integer

FK referencing the place’s category.

name

string

The place name.

description

string

Long-form description of the place.

address

string

Street address of the place.

latitude

number | null

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

longitude

number | null

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

average_rating

number

Mean of all review ratings for the place, rounded to one decimal place. Returns 0 if there are no reviews.

images

array

Polymorphic images attached to this place.

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\\Place".

images[].imageable_id

integer

ID of the owning place.

city

object

The city this place belongs to.

Show city fields

city.id

integer

City ID.

city.name

string

City name.

city.description

string | null

City description.

city.country

string

Country of the city.

category

object

The category this place belongs to.

Show category fields

category.id

integer

Category ID.

category.name

string

Category name.

category.description

string | null

Category description.

reviews

array

All reviews submitted for this place via the polymorphic reviewable morph relation. Each review includes the author’s user object.

Show review fields

reviews[].id

integer

Review ID.

reviews[].reviewable_type

string

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

reviews[].reviewable_id

integer

ID of the reviewed place.

reviews[].user_id

integer

ID of the user who submitted the review.

reviews[].rating

integer

Numeric rating provided by the reviewer.

reviews[].comment

string | null

Optional written comment.

reviews[].user

object

The user who authored the review (id, name, email, role_id). The password and remember_token fields are hidden.

reviews[].created_at

string

ISO 8601 review creation timestamp.

reviews[].updated_at

string

ISO 8601 review last-update timestamp.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-update timestamp.

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

Example request

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

Example response (200)

{
  "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.4036299,
  "longitude": 2.1743558,
  "average_rating": 4.8,
  "images": [
    {
      "id": 21,
      "url": "https://example.com/images/sagrada.jpg",
      "imageable_type": "App\\Models\\Place",
      "imageable_id": 3,
      "created_at": "2026-05-01T08:00:00.000000Z",
      "updated_at": "2026-05-01T08:00:00.000000Z"
    }
  ],
  "city": {
    "id": 1,
    "name": "Barcelona",
    "description": "A vibrant city on the northeastern coast of Spain.",
    "country": "Spain",
    "created_at": "2026-05-01T08:00:00.000000Z",
    "updated_at": "2026-05-01T08:00:00.000000Z"
  },
  "category": {
    "id": 2,
    "name": "Monuments",
    "description": "Historic monuments and architectural landmarks.",
    "created_at": "2026-05-01T08:00:00.000000Z",
    "updated_at": "2026-05-01T08:00:00.000000Z"
  },
  "reviews": [
    {
      "id": 5,
      "reviewable_type": "App\\Models\\Place",
      "reviewable_id": 3,
      "user_id": 42,
      "rating": 5,
      "comment": "Absolutely breathtaking. A must-see when visiting Barcelona.",
      "user": {
        "id": 42,
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "role_id": 2,
        "push_token": null,
        "created_at": "2026-05-15T10:30:00.000000Z",
        "updated_at": "2026-05-15T10:30:00.000000Z"
      },
      "created_at": "2026-05-10T14:22:00.000000Z",
      "updated_at": "2026-05-10T14:22:00.000000Z"
    },
    {
      "id": 9,
      "reviewable_type": "App\\Models\\Place",
      "reviewable_id": 3,
      "user_id": 17,
      "rating": 4,
      "comment": "Stunning architecture, but very crowded.",
      "user": {
        "id": 17,
        "name": "Grace Hopper",
        "email": "grace@example.com",
        "role_id": 2,
        "push_token": null,
        "created_at": "2026-05-12T09:00:00.000000Z",
        "updated_at": "2026-05-12T09:00:00.000000Z"
      },
      "created_at": "2026-05-13T11:05:00.000000Z",
      "updated_at": "2026-05-13T11:05:00.000000Z"
    }
  ],
  "created_at": "2026-05-01T08:00:00.000000Z",
  "updated_at": "2026-05-01T08:00:00.000000Z"
}

Overview

Endpoints

Places API Endpoints: List and Retrieve Place Data

List Places

Query parameters

Response — `200 OK`

Get Place

Path parameters

Response — `200 OK`

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​List Places

​Query parameters

​Response — 200 OK

​Get Place

​Path parameters

​Response — 200 OK

Build docs developers (and LLMs) love

List Places

Query parameters

Response — `200 OK`

Get Place

Path parameters

Response — `200 OK`