Places

Operations for discovering and managing places (scenes) in Genesis City. Places are deployable scenes located at specific parcel coordinates in the main Decentraland world.

List places with filters

get

https://places.decentraland.org/apihttp://localhost:4000/api

/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

limitinteger · max: 100Optional

Maximum number of places to return (max 100)

Default: 100Example: 20

offsetintegerOptional

Number of places to skip for pagination

Default: 0Example: 0

positionsstring[] · max: 1000Optional

Filter by specific parcel coordinates. Format: "x,y" (e.g., "-23,-96"). Can specify multiple positions to get places at any of those coordinates.

Example: ["-23,-96","-22,-96"]

only_favoritesbooleanOptional

Show only the authenticated user's favorite places. Requires authentication. Returns empty list if not authenticated.

Default: falseExample: false

only_highlightedbooleanOptional

Show only places marked as highlighted by moderators

Default: false

order_bystring · enumOptional

Sort places by this field:

• like_score: VP-weighted like ratio (default, best quality)
• most_active: Current user count (trending now)
• updated_at: Recently updated content
• created_at: Newly created places
• user_visits: Most visited in last 30 days

Default: like_scoreExample: most_activePossible values:

orderstring · enumOptional

Sort direction (ascending or descending)

Default: descExample: descPossible values:

with_realms_detailbooleanOptional

Include real-time realm and user count details. Experimental feature. Adds realms_detail array with per-realm user counts and active parcels. Note: Slightly slower response time.

Default: falseExample: true

searchstring · min: 3Optional

Full-text search in place title, description, and owner. Minimum 3 characters required. Returns empty array if too short.

Example: casino

categoriesstring[]Optional

Filter by categories (e.g., "art-gallery", "social", "game"). Get available categories from /categories endpoint. Multiple categories return places matching ANY category (OR logic).

Example: ["art-gallery","social"]

ownerstringOptional

Filter by owner's Ethereum address (case-insensitive). Must be a valid Ethereum address format.

Example: 0x1234567890123456789012345678901234567890Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Successfully retrieved places

application/json

400

Bad request - Invalid parameters or malformed request

application/json

500

Internal server error - Something went wrong on the server

application/json

get

/places

HTTPcURLJavaScriptPython

GET /api/places HTTP/1.1
Host: places.decentraland.org
Accept: */*

{
  "ok": true,
  "total": 150,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Art Gallery",
      "description": "Contemporary digital art exhibition",
      "image": "https://peer.decentraland.org/content/contents/QmXYZ...",
      "owner": "0xabcdef1234567890abcdef1234567890abcdef12",
      "positions": [
        "-23,-96",
        "-22,-96"
      ],
      "base_position": "-23,-96",
      "content_rating": "E",
      "likes": 45,
      "dislikes": 3,
      "like_score": 0.92,
      "favorites": 12,
      "user_count": 8,
      "user_visits": 234,
      "categories": [
        "art-gallery"
      ],
      "user_like": false,
      "user_dislike": false,
      "user_favorite": false
    }
  ]
}

Get specific places by IDs

post

https://places.decentraland.org/apihttp://localhost:4000/api

/places

Retrieve multiple specific places by their UUIDs in a single request. Maximum 100 place IDs per request.

Use Cases:

• Fetch details for a known set of places

• Resolve place IDs from external sources

• Batch operations for better performance

Note: Results are returned in the same order as requested IDs when available.

Query parameters

offsetintegerOptional

Number of results to skip

Default: 0

limitinteger · max: 100Optional

Maximum number of results (max 100)

Default: 100

order_bystring · enumOptional

Sort field

Default: like_scorePossible values:

orderstring · enumOptional

Sort direction

Default: descPossible values:

searchstring · min: 3Optional

Optional text search filter (minimum 3 characters)

Bodystring · uuid[]

application/json

string · uuid[] · min: 1 · max: 100Optional

Responses

200

Successfully retrieved places

application/json

400

Bad request - Invalid parameters or malformed request

application/json

post

/places

HTTPcURLJavaScriptPython

POST /api/places HTTP/1.1
Host: places.decentraland.org
Content-Type: application/json
Accept: */*
Content-Length: 79

[
  "550e8400-e29b-41d4-a716-446655440000",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
]

{
  "ok": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Art Gallery",
      "description": "A contemporary art gallery featuring digital sculptures and interactive installations.",
      "image": "https://peer.decentraland.org/content/contents/QmXYZ...",
      "owner": "0xabcdef1234567890abcdef1234567890abcdef12",
      "positions": [
        "-23,-96",
        "-22,-96",
        "-23,-95"
      ],
      "base_position": "-23,-96",
      "contact_name": "John Doe",
      "contact_email": "[email protected]",
      "content_rating": "T",
      "likes": 45,
      "dislikes": 3,
      "like_score": 0.92,
      "like_rate": 0.94,
      "favorites": 12,
      "disabled": false,
      "disabled_at": "2026-01-22T00:28:41.935Z",
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-06-20T14:45:00Z",
      "deployed_at": "2023-06-20T14:45:00Z",
      "user_like": false,
      "user_dislike": false,
      "user_favorite": true,
      "user_count": 8,
      "user_visits": 234,
      "categories": [
        "art-gallery",
        "social"
      ],
      "realms_detail": [
        {
          "serverName": "unicorn",
          "url": "https://realm-provider.decentraland.org/main",
          "usersCount": 145,
          "userParcels": [
            [
              -23,
              -96
            ],
            [
              0,
              0
            ],
            [
              -22,
              -95
            ]
          ]
        }
      ]
    }
  ],
  "total": 150
}

Get a specific place by ID

get

https://places.decentraland.org/apihttp://localhost:4000/api

/places/{place_id}

Retrieve detailed information about a single place by its UUID.

Returns 404 if the place doesn't exist or has been disabled.

Performance: This endpoint includes aggregated user data (likes, favorites, visits).

Path parameters

place_idstring · uuidRequired

Unique identifier (UUID) of the place

Example: 550e8400-e29b-41d4-a716-446655440000

Query parameters

with_realms_detailbooleanOptional

Include real-time realm and user distribution data

Default: false

Responses

200

Place found and returned successfully

application/json

404

Resource not found - Place/world doesn't exist or is disabled

application/json

get

/places/{place_id}

HTTPcURLJavaScriptPython

GET /api/places/{place_id} HTTP/1.1
Host: places.decentraland.org
Accept: */*

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Genesis Plaza",
    "description": "The main plaza of Decentraland",
    "base_position": "0,0",
    "user_count": 42,
    "categories": [
      "social",
      "event"
    ]
  }
}

Get categories for a place

get

https://places.decentraland.org/apihttp://localhost:4000/api

/places/{place_id}/categories

Retrieve all categories assigned to a specific place.

Categories are automatically assigned based on scene tags and can also be manually curated.

Path parameters

place_idstring · uuidRequired

UUID of the place

Responses

200

Categories retrieved successfully

application/json

404

Resource not found - Place/world doesn't exist or is disabled

application/json

500

Internal server error - Something went wrong on the server

application/json

get

/places/{place_id}/categories

HTTPcURLJavaScriptPython

GET /api/places/{place_id}/categories HTTP/1.1
Host: places.decentraland.org
Accept: */*

{
  "ok": true,
  "data": [
    {
      "name": "art-gallery",
      "active": true,
      "count": 45,
      "i18n": {
        "en": "Art Gallery"
      }
    }
  ]
}

Update place content rating 🔒

put

https://places.decentraland.org/apihttp://localhost:4000/api

/places/{place_id}/rating

Update the content rating for a place. Requires authentication.

Content ratings help users filter appropriate content:

• PR (Pre-Teen): Suitable for ages 10+

• E (Everyone): Suitable for all ages

• T (Teen): Suitable for ages 13+

• A (Adult): Suitable for ages 18+, may contain mature content

• R (Restricted): Adults only, explicit content

Note: Only authorized moderators can change ratings.

Authorizations

BearerAuth

AuthorizationstringRequired

Decentraland authentication token obtained from the Decentraland SDK or auth services.

To authenticate:

1. Use Decentraland's authentication SDK in your application
2. Get the auth token from the SDK
3. Include in requests: Authorization: Bearer <token>

Path parameters

place_idstring · uuidRequired

UUID of the place to rate

Body

application/json

content_ratingstring · enumRequired

New content rating:

• PR (Pre-Teen): Ages 10+
• E (Everyone): All ages
• T (Teen): Ages 13+
• A (Adult): Ages 18+, mature content
• R (Restricted): Adults only, explicit content

Example: TPossible values:

commentstringOptional

Optional explanation for the rating change (for moderation log)

Example: Updated due to new interactive content

Responses

200

Rating updated successfully

application/json

401

Unauthorized - Missing or invalid authentication token

application/json

403

Forbidden - user not authorized to update ratings

application/json

404

Resource not found - Place/world doesn't exist or is disabled

application/json

put

/places/{place_id}/rating

HTTPcURLJavaScriptPython

PUT /api/places/{place_id}/rating HTTP/1.1
Host: places.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "content_rating": "T",
  "comment": "Contains mild fantasy violence"
}

{
  "ok": true
}

Get lightweight place status

post

https://places.decentraland.org/apihttp://localhost:4000/api

/places/status

Retrieve basic status information for multiple places (up to 100).

Lightweight Alternative: Returns only essential fields (ID, title, position, disabled status). Use this instead of full place details when you only need to check if places exist or are enabled.

Performance: Faster than full place queries, suitable for status checks.

Bodystring · uuid[]

application/json

string · uuid[] · min: 1 · max: 100Optional

Responses

200

Status retrieved successfully

application/json

400

Bad request - Invalid parameters or malformed request

application/json

post

/places/status

HTTPcURLJavaScriptPython

POST /api/places/status HTTP/1.1
Host: places.decentraland.org
Content-Type: application/json
Accept: */*
Content-Length: 79

[
  "550e8400-e29b-41d4-a716-446655440000",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
]

{
  "ok": true,
  "total": 2,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Art Gallery",
      "base_position": "-23,-96",
      "disabled": false,
      "world": false,
      "world_name": null
    }
  ]
}