---
title: "List places with filters"
method: GET
path: "/places"
tags: ["Places"]
---

# List places with filters

`GET /places`

Retrieve a paginated list of places (scenes) in Genesis City with extensive filtering and sorting options.

**Common Use Cases:**
- Get most popular places: `?order_by=like_score&limit=20`
- Search by name: `?search=casino`
- Find places at coordinates: `?positions=-23,-96`
- Get user's favorites: `?only_favorites=true` (requires auth)

**Performance Tips:**
- Use pagination (limit/offset) for large result sets
- Cache results when possible
- Use `with_realms_detail=true` only when you need real-time user counts

## Query parameters

- `limit` integer
- `offset` integer
- `positions` string[]
- `only_favorites` boolean
- `only_highlighted` boolean
- `order_by` 'like_score' | 'most_active' | 'updated_at' | 'created_at' | 'user_visits'
- `order` 'asc' | 'desc'
- `with_realms_detail` boolean
- `search` string
- `categories` string[]
- `owner` string
- `sdk` string

## Response `200`

Successfully retrieved places

- object
  - `ok` boolean
  - `data` object[]
    - `id` string, uuid — Persistent unique identifier for the place. This UUID is maintained across scene redeployments as long as the scene keeps the same base parcel or contains all previous parcels. See "Place ID Semantics" in the API description for details.
    - `title` string, nullable — Display name of the place
    - `description` string, nullable — Long-form description of the place content
    - `image` string, uri, nullable — URL to the place thumbnail/preview image (from navmapThumbnail or generated)
    - `owner` string, nullable — Ethereum address of the place owner
    - `positions` string[] — All parcel coordinates occupied by this place. Places can span multiple parcels. **UUID Preservation:** If a new deployment contains all these parcels plus additional ones, the Place UUID is preserved (scene growth). However, if parcels are removed or changed, the UUID may change unless the base_position remains the same.
    - `base_position` string — Primary/spawn coordinate for the place. This is the main parcel where users spawn when entering the scene. **Important:** The base parcel is key to Place ID persistence - keeping the same base parcel across deployments preserves the Place UUID and all associated user data (favorites, likes, etc.).
    - `contact_name` string, nullable — Contact person name for the place
    - `contact_email` string, nullable — Contact email for the place
    - `content_rating` 'PR' | 'E' | 'T' | 'A' | 'R' — Age appropriateness rating: - PR: Pre-Teen (10+) - E: Everyone (all ages) - T: Teen (13+) - A: Adult (18+) - R: Restricted (18+, explicit)
    - `likes` integer — Total number of likes received
    - `dislikes` integer — Total number of dislikes received
    - `like_score` number, nullable — Quality score (0-1) based on VP-weighted likes/dislikes. Higher score = better quality. Null if insufficient votes.
    - `like_rate` number, nullable — Simple like ratio (likes / total votes), not VP-weighted
    - `ranking` number, nullable — External ranking value for custom ordering
    - `highlighted` boolean — True if this place is highlighted/featured by administrators. Highlighted places appear at the top of listing endpoints.
    - `favorites` integer — Number of users who favorited this place
    - `disabled` boolean — True if place is disabled (not shown publicly)
    - `disabled_at` string, date-time, nullable — Timestamp when place was disabled
    - `created_at` string, date-time — When the place was first created
    - `updated_at` string, date-time — Last update to place metadata
    - `deployed_at` string, date-time — Last scene deployment timestamp
    - `user_like` boolean — True if authenticated user liked this place
    - `user_dislike` boolean — True if authenticated user disliked this place
    - `user_favorite` boolean — True if authenticated user favorited this place
    - `user_count` integer — Current number of users in the place (real-time)
    - `user_visits` integer — Total unique users who visited in the last 30 days
    - `categories` string[] — Categories/tags assigned to this place
    - `realms_detail` object[] — Per-realm user distribution (only if with_realms_detail=true)
      - `serverName` string — Human-readable realm server name
      - `url` string, uri — Realm connection URL
      - `usersCount` integer — Total users currently in this realm
      - `userParcels` array[] — Coordinates where users are located in this realm
        - integer[] — [x, y] coordinate pair
    - `sdk` string, nullable — SDK/runtime version (e.g., "7" for SDK7)
    - `connected_addresses` string[] — List of wallet addresses currently connected to this place. Only included when `with_connected_users=true` query parameter is set.
  - `total` integer — Total number of places matching the query (for pagination)

## Other responses

- `400` — Bad request - Invalid parameters or malformed request
- `500` — Internal server error - Something went wrong on the server

---

[API](https://skmtc.net/decentraland/apis/realm-provider-api.md) · [All operations](https://skmtc.net/decentraland/apis/realm-provider-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/decentraland/realm-provider-api/revisions/d94e0e0f1821/schema)