# Add weather radar map tiles and layers with MyRadar's API

MyRadar's layers API serves x/y/z PNG radar tiles for a tile layer in Leaflet, Mapbox or Google Maps, renders a layer over a bounding box as an image or data file, and returns a layer's value at points. Every tile, image or point call is one `GET` at $0.02 per 100 requests, sent with `Authorization: Bearer <token>` for an agent credential that holds a plan. A map view costs one request per tile it loads.

## At a glance

- **Endpoints:** `GET https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/listlayers`, `/v1/layers/layerinfo/{layer}`, `/v1/layers/tile/{cycle_time}/{image_time}/{zoom}/{tile_x}/{tile_y}`, `/v1/layers/layer/{layer}/{valid_time}/{ul_lat}/{ul_lon}/{lr_lat}/{lr_lon}/{width}/{height}`, `/v1/layers/point/{layer}/{valid_time}`
- **Header:** `Authorization: Bearer <token>` on every call, including every tile
- **Price:** $0.02 per 100 requests on Credits. One call is one request, so a view costs the number of tiles it loads times that rate.
- **Payment:** buy a plan once with `POST https://agents.myradar.dev/zcj/1jxligfy6qto/plans/{planId}/purchase`. Only that purchase answers with a 402. Layer calls draw on the plan.
- **Response:** the layer list as a JSON array of names. A tile as a PNG with the color scale applied. A box as PNG, NetCDF, CSV, JSON or animated GIF. Point values as JSON or CSV.
- **Time formats:** tiles take `cycle_time` and `image_time` as `YYYYmmddHHMM`. Point requests take `valid_time` as `YYYYmmdd.HHMM`.
- **Full purchase flow:** [the buyer skill](https://agents.myradar.dev/zcj/1jxligfy6qto/SKILL.md)

## Get access once

Calls on this storefront are sold on plans, not per call. A plan is bought once with an agent credential, the bearer the storefront issues, at `/plans/{planId}/purchase`. The plan ids are listed in [the catalog](https://agents.myradar.dev/zcj/1jxligfy6qto/manifest.json).

The purchase answers with a 402, the price quote that you pay and then retry. [The buyer skill](https://agents.myradar.dev/zcj/1jxligfy6qto/SKILL.md) covers registration, payment and recovery. No upstream API key is needed.

## Request radar tiles for a map

1. List the layers. Take layer names from this list exactly as it returns them, and never guess one:

   ```bash
   curl -s https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/listlayers \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The response is a JSON array of strings, one layer name each. This call returned 93 layer names and drew $0.0002 from Credits, billed at $0.02 per 100 requests.

2. Read a layer's information:

   ```bash
   curl -s "https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/layerinfo/{layer}" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The response gives the contour levels suggested for the layer, a color in R,G,B,A for every level, and `time_step`, the interval between one image of the layer and the next.

3. Request one tile. Set `cycle_time` and `image_time` as `YYYYmmddHHMM`. Set `zoom`, `tile_x` and `tile_y` to the map's z, x and y:

   ```bash
   curl -s "https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/tile/{cycle_time}/{image_time}/{zoom}/{tile_x}/{tile_y}" \
     -H "Authorization: Bearer $ACCESS_TOKEN" -o tile.png
   ```

   The response is a single PNG for that tile, colored with the radar layer's scale.

4. Load tiles into the map through code that adds the bearer header, such as your own tile loader or a proxy you run. Each tile the map loads is a separate request, a tile request without the header is refused with `401 bearer_required`, and a plain tile-layer URL sends no header. Never put the token in the tile URL.

## Render a box or read values at points

To render a box, send one request with the upper left and lower right corners and the output size:

```bash
curl -s "https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/layer/{layer}/{valid_time}/{ul_lat}/{ul_lon}/{lr_lat}/{lr_lon}/{width}/{height}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -o box.png
```

| Output wanted | Query parameters |
| --- | --- |
| Colored PNG (default) | none |
| Raw values | `apply_color=false` |
| NetCDF | `as_netcdf=true` |
| Tabular values | `as_csv=true` or `as_json=true` |
| Animated GIF over a map background | `as_gif=true`, with `num_images` (default 12) and `zoom` (default 8) |
| Another projection | `epsg` (default 3857) |

To read values at points, send `latlons` as a JSON array of `[lat, lon]` pairs and `valid_time` as `YYYYmmdd.HHMM`. Add `as_csv=true` for CSV:

```bash
curl -s --get "https://agents.myradar.dev/zcj/1jxligfy6qto/v1/layers/point/{layer}/{valid_time}" \
  --data-urlencode 'latlons=[[41.5,-105.1]]' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Budget a map view

Each call is one request. A map's cost therefore scales with the number of tiles it loads, not the number of maps. The tile counts below are examples; count the tiles your own view loads.

| Use | Requests | Cost on Credits |
| --- | --- | --- |
| Example: one view of 12 tiles | 12 | $0.0024 |
| Example: that view across 10 image times | 120 | $0.024 |
| One box image or GIF, or one point call with several pairs | 1 | $0.02 per 100 requests |

The monthly plans bill the same request at a lower rate: Starter at $0.199 per thousand requests, Pro at $0.133 per thousand requests and Platinum at $0.11 per thousand requests. Their monthly fees are listed in [the catalog](https://agents.myradar.dev/zcj/1jxligfy6qto/manifest.json) and compared in [Pricing](/guides/pricing).

A response drawn from a plan carries a `zc-billing` header with `fundingSource`, `chargedUsd` and `remainingCreditUsd`.

## Limits

- The tile path takes `cycle_time`, `image_time`, `zoom`, `tile_x` and `tile_y`.
- One tile per request.
- Every call draws on a plan. A call without a bearer is refused with `401 bearer_required`.
- Access tokens are short-lived. Exchange the stored assertion for a fresh one when a token expires.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call carried no agent credential | Register at [auth.md](https://agents.myradar.dev/zcj/1jxligfy6qto/auth.md), then retry with the bearer |
| `401 invalid_token`, `reason` `token_expired` | The access token expired | Re-exchange the stored assertion and retry |
| `403 plan_required` | No plan you hold covers the call | Buy one of the plans in the body's `plans`, then retry |
| `usage_exhausted` | The plan's credit ran out | Top up with `POST https://agents.myradar.dev/zcj/1jxligfy6qto/extend` and `{"amountUsd": "..."}` |
| `422` | A path or query value failed validation | Check names against the layer list and the time formats |

## Frequently asked questions

### Do MyRadar radar tiles work with Leaflet, Mapbox and Google Maps?

Yes. The tile endpoint returns x/y/z PNG tiles for a tile layer in any of the three. Each tile request must carry `Authorization: Bearer <token>`, so load tiles through code or a proxy that adds the header.

### How much does a weather radar map cost to show?

The number of tiles loaded times the rate. At $0.02 per 100 requests, a 12-tile view is $0.0024, and every pan, zoom or new image time that loads more tiles adds more requests.

### Which radar and weather layers are available?

`GET /v1/layers/listlayers` returns every available radar and model layer name as a JSON array. Use those names in the layer information, box and point requests.

### Can I get layer data instead of a colored image?

Yes. On the box request, set `apply_color=false` for raw values, or `as_netcdf`, `as_csv` or `as_json` for data files. The point request returns the layer's value at each `[lat, lon]` pair.

### Do I need a MyRadar API key?

No. Calls use the agent credential the storefront issues, together with a plan bought once with it. No upstream API key is needed.

## Keep reading

- [The buyer skill](https://agents.myradar.dev/zcj/1jxligfy6qto/SKILL.md): the full purchase flow
- [MyRadar weather API pricing](/guides/pricing)
- [MyRadar API errors and recovery](/guides/errors)

---

Updated 2026-10-20. All MyRadar guides: https://agents.myradar.dev/guides.md. Storefront: https://agents.myradar.dev/zcj/1jxligfy6qto/llms.txt.