Getting started

Quickstart

Create an API key and make your first elevation lookup and STAC search in under five minutes.

1. Create an API key

Sign up or sign in — the Free plan needs no card.
Open Dashboard → API keys and create a key.
Copy it immediately — the full key is shown once.

Keep the key out of source control. The examples below read it from the DARLY_API_KEY environment variable:

Shell

export DARLY_API_KEY="dk_..."

2. Look up an elevation

Ground elevation (DTM) for a point in Montréal:

curl "https://api.darly.io/v1/elevation/point?lat=45.51&lon=-73.56" \
  -H "X-API-Key: $DARLY_API_KEY"

import os
import requests

resp = requests.get(
    "https://api.darly.io/v1/elevation/point",
    params={"lat": 45.51, "lon": -73.56},
    headers={"X-API-Key": os.environ["DARLY_API_KEY"]},
)
resp.raise_for_status()
print(resp.json()["result"])

const resp = await fetch(
  "https://api.darly.io/v1/elevation/point?lat=45.51&lon=-73.56",
  { headers: { "X-API-Key": process.env.DARLY_API_KEY } },
)
const { result } = await resp.json()
console.log(result)

{
  "status": "OK",
  "result": {
    "lat": 45.51,
    "lon": -73.56,
    "elevation": 36.42,
    "collection": "can-nrcan-hrdem-1m",
    "vertical_datum": "egm2008",
    "surface": "dtm",
    "resolution": 1.0
  }
}

Darly picked the finest dataset covering the point — here 1 m lidar from NRCan HRDEM. Elevations are always meters. Batch lookups, path sampling, surface/vertical-datum options: see the Elevation API reference.

3. Search the catalog

The same host is a full STAC API. Find 1 m lidar items around Vancouver:

curl -X POST "https://api.darly.io/search" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["can-nrcan-hrdem-1m"],
    "bbox": [-123.3, 49.1, -122.9, 49.4],
    "limit": 5
  }'

from pystac_client import Client

catalog = Client.open("https://api.darly.io")
search = catalog.search(
    collections=["can-nrcan-hrdem-1m"],
    bbox=[-123.3, 49.1, -122.9, 49.4],
    max_items=5,
)
for item in search.items():
    print(item.id, item.assets["dtm"].href)

const resp = await fetch("https://api.darly.io/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    collections: ["can-nrcan-hrdem-1m"],
    bbox: [-123.3, 49.1, -122.9, 49.4],
    limit: 5,
  }),
})
const { features } = await resp.json()
for (const item of features) console.log(item.id, item.assets.dtm?.href)

STAC search works without a key (30 requests/min per IP); sending your key raises the limit to your plan's. See the STAC catalog docs.

4. Extract a raster

Clip a GeoTIFF DEM of downtown Montréal — a 512 px preview works on the Free plan:

curl -G "https://api.darly.io/v1/elevation/raster" \
  --data-urlencode "bbox_left=-73.60" \
  --data-urlencode "bbox_bottom=45.49" \
  --data-urlencode "bbox_right=-73.54" \
  --data-urlencode "bbox_top=45.53" \
  --data-urlencode "width_px=512" \
  --data-urlencode "height_px=512" \
  -H "X-API-Key: $DARLY_API_KEY" \
  -o montreal-dtm.tif

import os
import requests

resp = requests.get(
    "https://api.darly.io/v1/elevation/raster",
    params={
        "bbox_left": -73.60, "bbox_bottom": 45.49,
        "bbox_right": -73.54, "bbox_top": 45.53,
        "width_px": 512, "height_px": 512,
    },
    headers={"X-API-Key": os.environ["DARLY_API_KEY"]},
)
resp.raise_for_status()
with open("montreal-dtm.tif", "wb") as f:
    f.write(resp.content)

The response is a cloud-optimized GeoTIFF (float32 meters, -9999 nodata) that opens directly in QGIS, GDAL, or rasterio. Full parameter reference: raster extracts.

Next steps

Authentication — header options, key management, how quotas attach to your account.
Rate limits & quotas — what each plan includes and every error shape.
Coverage & datasets — which data answers your queries, and where.
COG downloads — whole-file source downloads on paid plans.