LAND API Reference

Base URL: https://api.decentraland.org/

Specify version: https://api.decentraland.org/v1

Bids
Contributions
Districts
Estates
Mortgages
Map
Parcels
Publications
Translations

Bids

GET /bids/:id

Description

Returns a bid by its id.

URI Params

name	type	description
id	string	The id of the bid

Request Example:

GET /bids/0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea

Response Example

{
  "ok": true,
  "data": {
    "id": "0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea",
    "token_address": "0x124bf28a423b2ca80b3846c3aa0eb944fe7ebb95",
    "token_id": "31",
    "bidder": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
    "seller": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
    "price": 2,
    "expires_at": "1551495590000",
    "fingerprint": "0x7bf0da414abc768d638b486dfc3330abd361aa7d7916d673072d4e3776ea9287",
    "status": "sold",
    "asset_id": "31",
    "asset_type": "estate",
    "block_number": 4924562,
    "block_time_created_at": "1548876122000",
    "block_time_updated_at": "1548876183000",
    "created_at": "2019-01-31T13:42:40.697Z",
    "updated_at": "2019-02-04T12:42:23.017Z"
  }
}

GET /addresses/:address/bids

Description

Returns a list of bids where the seller or bidder is the given address.

URI Params

name	type	description
address	string	An Ethereum address

Query Params

name	type	default	description
status	enum	all	Filter estates by publications status: `open`, `cancelled` or `sold`

Request Example:

GET /addresses/0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xfbeb6c5f702d3be5564872cd68bc96c683b0029d8116feb79058669c6fe40d1d",
      "token_address": "0x7a73483784ab79257bb11b96fd62a2c3ae4fb75b",
      "token_id": "1.1579208923731619542357098500868790784067953708956584089131272353293770581592e+77",
      "bidder": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "seller": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "price": 1,
      "expires_at": "1551409156000",
      "fingerprint": "0x",
      "status": "sold",
      "asset_id": "145,-79",
      "asset_type": "parcel",
      "block_number": 4918744,
      "block_time_created_at": "1548787699000",
      "block_time_updated_at": "1548787921000",
      "created_at": "2019-01-31T13:42:40.437Z",
      "updated_at": "2019-02-04T12:42:22.785Z"
    }
  ]
}

GET /parcels/:x/:y/bids

Description

Returns a list of bids placed on a given Parcel.

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

Query Params

name	type	default	description
status	enum	all	Filter estates by publications status: `open`, `cancelled` or `sold`
bidder	string	N/A	The Ethereum address of the bidder
sanitize	boolean	true	If false, will retrieve all the bids property

Request Example:

GET /parcels/145,-79/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xfbeb6c5f702d3be5564872cd68bc96c683b0029d8116feb79058669c6fe40d1d",
      "token_address": "0x7a73483784ab79257bb11b96fd62a2c3ae4fb75b",
      "token_id": "1.1579208923731619542357098500868790784067953708956584089131272353293770581592e+77",
      "bidder": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "seller": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "price": 1,
      "expires_at": "1551409156000",
      "fingerprint": "0x",
      "status": "sold",
      "asset_id": "145,-79",
      "asset_type": "parcel",
      "block_number": 4918744,
      "block_time_created_at": "1548787699000",
      "block_time_updated_at": "1548787921000",
      "created_at": "2019-01-31T13:42:40.437Z",
      "updated_at": "2019-02-04T12:42:22.785Z"
    }
  ]
}

GET /estates/:id/bids

Description

Returns a list of bids placed on a given Estate.

URI Params

name	type	description
id	string	The id of the estate

Query Params

name	type	default	description
status	enum	all	Filter estates by publications status: `open`, `cancelled` or `sold`
bidder	string	N/A	The Ethereum address of the bidder
sanitize	boolean	true	If false, will retrieve all the bids property

Request Example:

GET /estates/1/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea",
      "token_address": "0x124bf28a423b2ca80b3846c3aa0eb944fe7ebb95",
      "token_id": "1",
      "bidder": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "seller": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "price": 2,
      "expires_at": "1551495590000",
      "fingerprint": "0x7bf0da414abc768d638b486dfc3330abd361aa7d7916d673072d4e3776ea9287",
      "status": "sold",
      "asset_id": "1",
      "asset_type": "estate",
      "block_number": 4924562,
      "block_time_created_at": "1548876122000",
      "block_time_updated_at": "1548876183000",
      "created_at": "2019-01-31T13:42:40.697Z",
      "updated_at": "2019-02-04T12:42:23.017Z"
    }
  ]
}

GET /bids/:address/assets

Description

Returns a list of bid assets where the seller or bidder is the given address.

URI Params

name	type	description
address	string	An Ethereum address

Query Params

name	type	default	description
status	enum	all	Filter estates by publications status: `open`, `cancelled` or `sold`

Request Example:

GET /bids/0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9/assets

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "12345",
      "owner": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
      "data": {
        "ipns": "",
        "name": "My Estate",
        "parcels": [
          { "x": -30, "y": -121 },
          { "x": -29, "y": -121 }
        ],
        "version": 0,
        "description": "My estate is awesome"
      },
      "last_transferred_at": "1548929430000",
      "tx_hash": "0x6d1f7cad7419af31b6b1f65205c5336200a1662e35ed9083d5f4323f95cb9dd6",
      "token_id": "12345",
      "update_operator": "0x0000000000000000000000000000000000000000"
    },
    {
      "id": "-74,-52",
      "x": -74,
      "y": -52,
      "auction_price": 2443,
      "district_id": null,
      "owner": "0xdeadbeeffaceb00c",
      "data": {
        "version": 0,
        "name": "My Parcel",
        "description": "My parcel is awesome",
        "ipns": ""
      },
      "auction_owner": "0xdeadbeeffaceb00c",
      "tags": {},
      "last_transferred_at": null,
      "in_estate": false
    }
  ]
}

Contributions

GET /addresses/:address/contributions

Description

Returns all the contributions to districts for a given address

URI Params

name	type	description
address	string	An Ethereum address

Response Example

{
  "ok": true,
  "data": [
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "219ac351-e6ce-4e17-8b84-eb008afddf69",
      "land_count": "5"
    },
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "d9bfa18a-c856-457d-8d85-e2dc3b7648a1",
      "land_count": "15"
    },
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "f5d8e722-fdce-4d41-b38b-adfed2e0cf6c",
      "land_count": "10"
    }
  ]
}

Districts

GET /districts

Returns all the districts in Genesis City

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "106f1557-4a92-41a4-9f18-40fcb90b4031",
      "name": "Dragon City",
      "description": "A perfect combination of China’s ancient culture and Western modernization, a reflection of both the Eastern and Western civilizations.",
      "link": "https://github.com/decentraland/districts/issues/30",
      "public": true,
      "parcel_count": "6485",
      "center": "105,-89"
    },
    {
      "id": "219ac351-e6ce-4e17-8b84-eb008afddf69",
      "name": "AETHERIAN project",
      "description": "Aetherian City will be one of the main attractions for visitors and dwellers of Decentraland, as it intends to be the largest cyberpunk-agglomeration of the metaverse.",
      "link": "https://github.com/decentraland/districts/issues/33",
      "public": true,
      "parcel_count": "10005",
      "center": "106,105"
    }
  ]
}

Estates

GET /estates

Description

Returns a list of Estates, paginated, sorted, and filtered according to the query params used.

name	type	default	description
status	enum	`open`	Filter estates by publications status: `open`, `cancelled` or `sold`
sort_by	enum	`created_at`	Property to order by: `price`, `created_at`, `block_time_updated_at` or `expires_at`
sort_order	enum	depends on `sort_by`	The order to sort by: `asc` or `desc`
limit	int	`20`	The number of results to be returned
offset	int	`0`	The number of results to skip (used for pagination)

Response Example

{
  "ok": true,
  "data": {
    "estates": [
      {
        "id": "12345",
        "owner": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
        "data": {
          "ipns": "",
          "name": "My Estate",
          "parcels": [
            { "x": -30, "y": -121 },
            { "x": -29, "y": -121 },
            { "x": -29, "y": -122 },
            { "x": -30, "y": -122 }
          ],
          "version": 0,
          "description": "My estate is awesome"
        },
        "last_transferred_at": "1548929430000",
        "tx_hash": "0x6d1f7cad7419af31b6b1f65205c5336200a1662e35ed9083d5f4323f95cb9dd6",
        "token_id": "12345",
        "update_operator": "0x0000000000000000000000000000000000000000",
        "publication": {
          "tx_hash": "0xbcad5e05351972174c05633e8965de0b05a5a0ce4c5415c1a392ffae20b1cab2",
          "tx_status": "confirmed",
          "owner": "0xf631c1ba09ee33e7649cac62ccb6d0f410f5647a",
          "price": 39500,
          "expires_at": 1554210000000,
          "status": "sold",
          "buyer": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
          "contract_id": "0xfe8288241f94ebf31c132b85eb9ee6b834fb27b4c564eab6ba18b3813fafda38",
          "block_number": 7151964,
          "block_time_created_at": 1548906378000,
          "block_time_updated_at": 1548929430000,
          "asset_type": "estate",
          "asset_id": "12345",
          "marketplace_address": "0x8e5660b4ab70168b5a6feea0e0315cb49c8cd539"
        }
      }
    ],
    "total": 80
  }
}

GET /addresses/:address/estates

Description

Returns all the Estates that belong to a given address

URI Params

name	type	description
address	string	An Ethereum address

Map

GET /map

Description

Returns all the parcels and estates in a given area

Query Params

name	type	min	max	description
nw	int	-150	150	The northwest coord of the area
se	int	-150	150	The southeast coord of the area

Request Example:

GET /map?nw=-10,10&se=10,-10

Result:

{
  "data": {
    "assets": {
      "parcels": [
        /* parcels */
      ],
      "estates": [
        /* estates */
      ]
    },
    "total": 441
  }
}

GET /map.png

Description

Returns a PNG of a section of the Genesis City map

Query Params

name	type	min	max	default	description
width	int	32	2048	500	The width of the PNG image in pixels
height	int	32	2048	500	The height of the PNG image in pixels
size	int	5	40	10	The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
center	coords	-150,-150	150,150	0,0	The coords on where to center the map
selected	list of coords	N/A	N/A	N/A	A list of coords separated by semicolons to render as “selected”
publications	boolean	N/A	N/A	false	If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /map.png?width=500&height=500&size=10&center=20,21&selected=20,20;20,21;20,22;20,23;19,21;21,21

Result:

map-1

GET /parcels/:x/:y/map.png

Description

Returns a PNG of a piece of the map center on a given parcel

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

Query Params

name	type	min	max	default	description
width	int	32	2048	500	The width of the PNG image in pixels
height	int	32	2048	500	The height of the PNG image in pixels
size	int	5	40	10	The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
publications	boolean	N/A	N/A	false	If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /parcels/-36/-125/map.png?height=500&width=500&size=10&publications=true

Result:

map-1

GET /estates/:id/map.png

Description

Same as /parcels/:x/:y/map.png, but instead of using x and y coordinates to determine the estate, its id is used.. Returns a PNG of a piece of the map center on a given estate

URI Params

name	type	description
id	string	The id of the estate

Query Params

name	type	min	max	default	description
width	int	32	2048	500	The width of the PNG image in pixels
height	int	32	2048	500	The height of the PNG image in pixels
size	int	5	40	10	The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
publications	boolean	N/A	N/A	false	If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /estates/23/map.png?height=500&width=500&size=10&publications=true

Result:

map-2

Mortgages

GET /mortgages/:address/parcels

Description

Returns a list of Parcels which has an active mortgage requested by a given address.

URI Params

name	type	description
address	string	An Ethereum address

Request Example:

GET /mortgages/0x374cc898638940452b6d7b34f6063170976026f0/parcels

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "-44,-144",
      "x": -44,
      "y": -144,
      "auction_price": null,
      "district_id": null,
      "owner": "0xaf592460d6a44517aba2fb0bcb02ee8f4103b502",
      "data": { "version": 0 },
      "auction_owner": null,
      "tags": {},
      "last_transferred_at": "1548424046000",
      "estate_id": null,
      "update_operator": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "auction_timestamp": null,
      "publication": null
    }
  ]
}

GET /addresses/:address/mortgages

Description

Returns all the mortgages requested by a given address

URI Params

name	type	description
address	string	An Ethereum address

Query params

name	type	default	description
status	enum	all	Filter parcels by publications status: `pending`, `cancelled`, `ongoing`, `paid`, `defaulted` or `claimed`

Request Example:

GET /addresses/0x374cc898638940452b6d7b34f6063170976026f0/mortgages

Result:

{
  "ok": true,
  "data": [
    {
      "tx_hash": "0xf67f78f63a116fb14a5a119c73505822beddab16c7f3c736e2f88fc48009760f",
      "tx_status": "confirmed",
      "block_number": 4929341,
      "status": "cancelled",
      "asset_id": "-102,-77",
      "asset_type": "parcel",
      "borrower": "0x374cc898638940452b6d7b34f6063170976026f0",
      "lender": null,
      "loan_id": 685,
      "mortgage_id": 16,
      "amount": 10,
      "is_due_at": "0",
      "expires_at": "1551571200000",
      "block_time_created_at": "1548943095000",
      "block_time_updated_at": "1548944551000",
      "created_at": "2019-01-31T13:58:53.067Z",
      "updated_at": "2019-02-04T12:42:23.047Z",
      "outstanding_amount": 0,
      "payable_at": "777600",
      "interest_rate": 15552000000000,
      "punitory_interest_rate": 10367989632000,
      "paid": 0,
      "started_at": null
    }
  ]
}

GET /parcels/:x/:y/mortgages

Description

Returns mortgages requested on a given parcel

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

Query Params

name	type	default	description
status	enum	all	Filter parcels by publications status: `pending`, `cancelled`, `ongoing`, `paid`, `defaulted` or `claimed`

Request Example:

GET /parcels/-102/-77/mortgages

Result:

{
  "ok": true,
  "data": [
    {
      "tx_hash": "0xf67f78f63a116fb14a5a119c73505822beddab16c7f3c736e2f88fc48009760f",
      "tx_status": "confirmed",
      "block_number": 4929341,
      "status": "cancelled",
      "asset_id": "-102,-77",
      "asset_type": "parcel",
      "borrower": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "lender": null,
      "loan_id": 685,
      "mortgage_id": 16,
      "amount": 10,
      "is_due_at": "0",
      "expires_at": "1551571200000",
      "block_time_created_at": "1548943095000",
      "block_time_updated_at": "1548944551000",
      "created_at": "2019-01-31T13:58:53.067Z",
      "updated_at": "2019-02-04T12:42:23.047Z",
      "outstanding_amount": 0,
      "payable_at": "777600",
      "interest_rate": 15552000000000,
      "punitory_interest_rate": 10367989632000,
      "paid": 0,
      "started_at": null
    }
  ]
}

Parcels

GET /parcels

Returns a list of parcels, paginated, sorted, and filtered according to the query params used.

Query Params

name	type	default	description
status	enum	`open`	Filter parcels by publications status: `open`, `cancelled` or `sold`
sort_by	enum	`created_at`	Property to order by: `price`, `created_at`, `block_time_updated_at` or `expires_at`
sort_order	enum	depends on `sort_by`	The order to sort by: `asc` or `desc`
limit	int	`20`	The number of results to be retuned
offset	int	`0`	The number of results to skip (used for pagination)

Response Example

{
  "ok": true,
  "data": {
    "parcels": [
      {
        "id": "-74,-52",
        "x": -74,
        "y": -52,
        "auction_price": 2443,
        "district_id": null,
        "owner": "0xdeadbeeffaceb00c",
        "data": {
          "version": 0,
          "name": "My Parcel",
          "description": "My parcel is awesome",
          "ipns": ""
        },
        "auction_owner": "0xdeadbeeffaceb00c",
        "tags": {
          "proximity": {
            "plaza": {
              "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
              "distance": 2
            },
            "road": {
              "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
              "distance": 0
            }
          }
        },
        "last_transferred_at": null,
        "in_estate": false,
        "publication": {
          "tx_hash": "0xdeadbeeffaceb00c",
          "tx_status": "confirmed",
          "owner": "0xdeadbeeffaceb00c",
          "price": 60000,
          "status": "open",
          "buyer": null,
          "contract_id": "0xdeadbeeffaceb00c",
          "block_number": 5812730,
          "expires_at": 1533081600000,
          "block_time_created_at": 1529352925000,
          "block_time_updated_at": null,
          "type": "parcel",
          "asset_id": "-74,-52",
          "marketplace_id": "0xdeadbeeffaceb00c"
        }
      }
    ],
    "total": 2
  }
}

GET /addresses/:address/parcels

Description

Returns all the parcels that belong to a given address

GET /parcels/:x/:y

Description

Returns a single parcel by its coords

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

Request Example:

GET /parcels/-48/-29

Response Example

{
  "ok": true,
  "data": {
    "id": "-48,-29",
    "x": -48,
    "y": -29,
    "auction_price": 2443,
    "district_id": null,
    "owner": "0xdeadbeeffaceb00c",
    "data": {
      "version": 0,
      "name": "My Parcel",
      "description": "My parcel is awesome",
      "ipns": ""
    },
    "auction_owner": "0xdeadbeeffaceb00c",
    "tags": {
      "proximity": {
        "plaza": {
          "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
          "distance": 2
        },
        "road": {
          "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
          "distance": 0
        }
      }
    },
    "last_transferred_at": null,
    "in_estate": false
  }
}

GET /parcels/:tokenId

Description

Returns a single parcel by its blockchain id (token id)

URI Params

name	type	default	description
tokenId	int, hex		The parcel blockchain id

Request Example:

GET /parcels/115792089237316195423570985008687907837276713420356456256678977458620023701475

GET /parcels/0xffffffffffffffffffffffffffffffd0ffffffffffffffffffffffffffffffe3

Response Example

### Response Example

```json
{
  "ok": true,
  "data": {
    "id": "-74,-52",
    "x": -74,
    "y": -52,
    "auction_price": 2443,
    "district_id": null,
    "owner": "0xdeadbeeffaceb00c",
    "data": {
      "version": 0,
      "name": "My Parcel",
      "description": "My parcel is awesome",
      "ipns": ""
    },
    "auction_owner": "0xdeadbeeffaceb00c",
    "tags": {
      "proximity": {
        "plaza": {
          "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
          "distance": 2
        },
        "road": {
          "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
          "distance": 0
        }
      }
    },
    "last_transferred_at": null,
    "in_estate": false
  }
}

GET /parcels/:x/:y/encodedId

Description

Returns the blockchain id (token id) by the parcel coordinates

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

Request Example:

GET /parcels/-48/-29/encodedId

Response Example

{
  "ok": true,
  "data": {
    "encoded_id": "0xffffffffffffffffffffffffffffffd0ffffffffffffffffffffffffffffffe3"
  }
}

Publications

GET /parcels/:x/:y/publications

Description

Returns all the publications that ever existed for a given parcel

URI Params

name	type	min	max	default	description
x	int	-150	150	0	The X coord of the parcel
y	int	-150	150	0	The Y coord of the parcel

GET /publications/:txHash

Description

Returns a specific publication by its transaction hash

URI Params

name	type	description
txHash	string	The transaction hash of a publication

Translations

GET /translations/:locale

Description

Returns all the available translations for a given locale

URI Params

name	type	description
locale	enum	One of the following locales: `en`, `es`, `fr`, `ko` or `zh`

Was this article useful?

Awesome!

Anything we can do to make it even better?

We're sorry!

Please let us know how we can improve our documentation.

Thank you!

Your feedback helps us improve everyone's experience in Decentraland.

Have a suggestion? Edit this doc on GitHub

LAND API Reference

Table of Contents

Bids

Description

URI Params

Request Example:

Response Example

Description

URI Params

Query Params

Request Example:

Response Example

Description

URI Params

Query Params

Request Example:

Response Example

Description

URI Params

Query Params

Request Example:

Response Example

Description

URI Params

Query Params

Request Example:

Response Example

Contributions

Description

URI Params

Response Example

Districts

Response Example

Estates

Description

Response Example

Description

URI Params

Map

Description

Query Params

Request Example:

Result:

Description

Query Params

Limits

Request Example:

Result:

Description

URI Params

Query Params

Limits

Request Example:

Result:

Description

URI Params

Query Params

Limits

Request Example:

Result:

Mortgages

Description

URI Params

Request Example:

Response Example

Description

URI Params

Query params

Request Example:

Result:

Description

URI Params

Query Params

Request Example:

Result:

Parcels

Query Params

Response Example

Description

Description