Skip to content

Quickstart

A guided tour of the three ADAM API surfaces in about 10 minutes: Swagger, the live HTML browser, and your own code. No account, no API key — the API is public.

Prerequisites

  • Python 3.11 or newer
  • uv (recommended) or pip
  • A modern browser for the first two steps

Step 1 — Poke Swagger (30 seconds)

Open the Swagger UI and expand the OGC Features API group. Click GET /collections, then Try it out → Execute. You get a JSON response listing every collection currently exposed. This is the formal contract — every parameter and response field is described there, and you can invoke any endpoint without writing a line of code.

Leave the tab open — you will come back to it.

Step 2 — Walk the live HTML browser (2 minutes)

Open /api/collections?f=html. This is the same endpoint, rendered as HTML: a navigable page with a link to each collection.

Click on adam.adam_eq_events. You land on the collection's metadata page, with links to its items, queryables, and tiles. Click Items. You are now looking at the current earthquake events as HTML. Click any feature to open it on its own page, including the dynamic fields pointing to derived products.

You have just walked the entire API like a website. This is the data-exploration surface — there is no better way to see what the API actually holds today.

Step 3 — Make the first call from Python (5 minutes)

Now the programmatic surface. Create a project and install httpx:

$ uv init adam-quickstart && cd adam-quickstart
$ uv add httpx

List all collections from Python:

import httpx

BASE = "https://api.adam.geospatial.wfp.org/api"

resp = httpx.get(f"{BASE}/collections")
resp.raise_for_status()

for c in resp.json()["collections"]:
    print(f"{c['id']:<40} {c['title']}")

Run it:

$ uv run python main.py
adam.adam_eq_events                      Earthquake Events
adam.adam_fl_events                      Flood Events
adam.adam_ts_events                      Tropical Storm Events
...

Now fetch features from one of them — filter by date and bounding box:

import httpx

BASE = "https://api.adam.geospatial.wfp.org/api"
COLLECTION = "adam.adam_eq_events"

resp = httpx.get(
    f"{BASE}/collections/{COLLECTION}/items",
    params={
        "bbox": "-180,-90,180,90",
        "datetime": "2026-01-01T00:00:00Z/..",
        "limit": 10,
        "sortby": "-datetime",
    },
)
resp.raise_for_status()

fc = resp.json()
print(f"{fc['numberMatched']} events matched, showing {fc['numberReturned']}:\n")
for f in fc["features"]:
    p = f["properties"]
    lon, lat = f["geometry"]["coordinates"]
    print(f"  {p.get('published_at', '?'):<25} M{p.get('mag', '?'):<5} ({lat:.2f}, {lon:.2f})")

The response is a standard GeoJSON FeatureCollection — every GIS library understands it.

Step 4 — Put it on a map (2 minutes)

For interactive rendering, the API gives you a ready-made StyleJSON you can feed straight to MapLibre. Save this as map.html next to your Python script:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>ADAM earthquakes</title>
  <link href="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css" rel="stylesheet">
  <script src="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js"></script>
  <style>body, html, #map { margin: 0; height: 100vh; }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    new maplibregl.Map({
      container: "map",
      style: "https://api.adam.geospatial.wfp.org/api/collections/adam.adam_eq_events/tiles/WebMercatorQuad/style.json",
      center: [30, 20],
      zoom: 2,
    });
  </script>
</body>
</html>

Open the file in a browser. You should see a world map with ADAM earthquake events rendered on top — same data you queried in Step 3, now from the Tiles surface, styled for you by the server.

Step 5 — Shortcut: the built-in viewer

If you just want to look at a collection without writing any code at all:

https://api.adam.geospatial.wfp.org/api/collections/adam.adam_eq_events/tiles/WebMercatorQuad/map.html

Every collection has one. Handy for sharing a quick link with a colleague.

What you learnt

  • Swagger (/api/docs) is where you discover endpoints and their exact contract
  • HTML browser (?f=html) is where you explore what is actually in the API today
  • Features (/items) give you GeoJSON for analysis; Tiles (/tiles, style.json) give you ready-to-render maps
  • The API is public — just call it

Next steps