LAND API Reference

Current documentation (including configuration details) for the LAND API v2.0 can be found here.

Bids and publications come form the nft-server, its documentation can be found here

Version 2.0 Migration Guide #

Following is a side-by-side comparison of v1 and v2 of the LAND API. Any version 1 endpoints with the tag Deprecated will be unavailable starting February 1st, 2021.

Any version 1 endpoints without the deprecation tag will remain working and supported, as there is no replacement in version 2.0.

There are several v1 endpoints without a v2 counterpart, but the corresponding data can still be found via a query to Decentraland’s subgraph on The Graph. Example queries are included for each endpoint group, where applicable.

Tiles #

The v1 tiles endpoint has been replaced with an improved v2 endpoint. The v2 endpoint returns a more readable and more easily parsed object. For an in depth discussion of these improvements, see this blogpost.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /v1/tiles`	Returns all tiles in the map, using the legacy format. Deprecated.	`GET /v2/tiles`	Returns all tiles in the map, using the new v2 format. This replaces v1 of the same endpoint, returning an object with a new, more useful shape.

Bids #

All of the v1 bid endpoints have been replaced with queries to the Graph. See the chart and example below for details.

V1 Endpoint	Description	V2 Endpoint
`GET /bids/:id`	Returns a bid by the bid’s ID. Deprecated	See example subgraph query below.
`GET /addresses/:address/bids`	Returns list of bids by the seller or bidder’s Ethereum address. Deprecated	See example subgraph query below.
`GET /parcels/:x/:y/bids`	Returns a list of bids placed on a given parcel. Deprecated	See example subgraph query below.
`GET /estates/:id/bids`	Returns a list of bids placed on a given estate. Deprecated	See example subgraph query below.
`GET /bids/:address/assets`	Returns a list of bid assets by the seller or bidder’s Ethereum address. Deprecated	See example subgraph query below.

To list open and non-expired bids where the expiration date is specified as a unix timestamp:

{
  bids(where:{ status: open, expiresAt_gt: 1611082372  }) {
    nft {
      name
      contractAddress
      tokenId
    }
    price
    bidder
    seller
  }
}

Districts and District Contributions #

V2 endpoints to expose data about Districts and District contributions are under active development. Until February 1st, 2021, you may still call the v1 endpoint. After that date, new documentation for the v2 endpoints will be published on this page.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /addresses/:address/contributions`	Returns all contributions to districts by the contributor’s Ethereum address. Deprecated	`GET /v2/addresses/:address/contributions`	This v2 endpoint is under active development, and will be functional on February 1st, 2021 when v1 is deprecated.
`GET /districts`	Returns a list of all districts in Genesis City. Deprecated	`GET /v2/addresses/:address/contributions`	This v2 endpoint is under active development, and will be functional on February 1st, 2021 when v1 is deprecated.

Estates #

While two v1 estate endpoints are replaced with Graph queries, version 2.0 introduces a new estate endpoint that allows you to return data about an estate based on the estates ID.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /estates`	Returns a list of Estates. Deprecated	See example subgraph query below.
`GET /addresses/:address/estates`	Returns all Estates belonging to the given Ethereum address. Deprecated	See example subgraph query below.
		`GET /v2/estates/:id`	New v2 endpoint that returns metadata about an estate with the given ID.

To obtain estate data, query the Graph for NFT entities with the condition:

{
  category: estate
}

Map #

The v1 map endpoint remains unchanged and supported.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /map`	Returns all parcels and estates in a given area. This endpoint is depcrecated and is replaced by `GET /v1/map.png`
`GET /map.png`	Returns a PNG image of a section of the map.	`GET /v1/map.png`	Returns a PNG image of a section of the map. This endpoint is still supported and functional! There is no v2 version of this endpoint, keep calling the v1 endpoint to get the same data.
`GET /parcels/:x/:y/map.png`	Returns a PNG image of a piece of the map centered on the given parcel.	`GET /v1/parcels/:x/:y/map.png`	Returns a PNG image of a map centered on a highlighted parcel with the given coordinates.
`GET /estates/:id/map.png`	Returns a PNG image of a piece of the map centered on an estate specified by the estate’s ID.	`GET /v1/estates/:id/map.png`	Returns a PNG image of a map centered on a highlighted estate with the given ID.

Mortgages #

The mortgage endpoints are all deprecated with the v2 release. Since mortgages are no longer supported in the marketplace, there’s no longer any data in this category to expose via an API or Graph query.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /mortgages/:address/parcels`	Returns list of parcels with an active mortgage requested by a given Ethereum address. Deprecated
`GET /addresses/:address/mortgages`	Returns all mortgages requested by a given Ethereum address. Deprecated
`GET /parcels/:x/:y/mortgages`	Returns all mortgages requested for a given parcel. Deprecated

parcels #

Some of the parcel endpoints have v2 counterparts, while others are replaced with queries to the Graph. See the chart below for details.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /parcels`	Returns a list of all parcels. Deprecated.	See the example subgraph query below.
`GET /addresses/:address/parcels`	Returns a list of all parcels belonging to a given address. Deprecated.	See the example subgraph query below.
`GET /parcels/:x/:y`	Returns a single parcel with the given coordinates. Deprecated.	`GET /v2/parcels/:x/:y`	Returns metadata about a parcel with the given coordinates. This new v2 endpoint queries The Graph instead of looking at the deprecated v1 server.
`GET /parcels/:tokenId`	Returns a single parcel based on its blockchain ID (also called a token ID). Deprecated.	`GET /v2/contracts/:address/tokens/:id`	Returns metadata about a parcel or estate with the given contract address and token/blockchain ID.
`GET /parcels/:x/:y/encodedId`	Returns the blockchain/token ID of a parcel based on its coordinates. Deprecated	`GET /v2/tiles?x1&x2&y1&y2&include=tokenId`	By setting both x1 and x2 to X and y1 and y2 to Y value, and including only the tokenId property you can find the same data using the new /v2/tiles endpoint.

To list all parcels owned by one specific address, submit this query to the Graph:

{
  nfts(where:{ category: parcel, owner: "0x..."  }) {
    parcel {
      x
      y
    }
  }
}

Publications #

The publications endpoints are all replaced with corresponding queries to the Graph.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /parcels/:x/:y/publications`	Returns all previous publications for a given parcel. Deprecated	See example subgraph query below.
`GET /publications/:txHash`	Returns a specific publication based on the publication’s transaction hash. Deprecated.	See example subgraph query below.

To list all open and non-expired orders, submit this query to the Graph:

{
  orders(where:{ status: open, expiresAt_gt: 1611082372  }) {
    nft {
      name
      contractAddress
      tokenId
    }
    price
  }
}

Translations #

This is a legacy endpoint that is only used by the UI. It remains supported and unchanged with the v2 release.

V1 Endpoint	Description	V2 Endpoint	Description
`GET /translations/:locale`	Returns all available translations for a given ‘locale’ where ‘locale’ can be ‘en’, ‘es’, ‘fr’, ‘ko’, or ‘zh’.