# Forecast road weather along a driving route with MyRadar's API

MyRadar's road weather time series forecasts road and atmospheric conditions along a driving route. The forecast follows where the vehicle will be at each step of the trip, and the same service covers a list of fixed sites or a past window. Each call is one request at $0.02 per 100 requests, drawn from a plan you buy once with an agent credential: send `GET https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/route` with `origin`, `destination`, `depart_time` and `Authorization: Bearer <token>`.

## At a glance

- **Route endpoint:** `GET https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/route`, with `origin` and `destination` as `lat,lon` and `depart_time` as `YYYYMMDD.HHMM`. All three are required.
- **Fixed sites:** `GET` or `POST https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/point`. **Past conditions:** `GET https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/hist/{begin_time}/{end_time}`.
- **Price:** one request per call, $0.02 per 100 requests. Starter, Pro and Platinum monthly plans bill $0.199 per thousand requests, $0.133 per thousand requests and $0.11 per thousand requests.
- **Payment:** calls draw on a plan. Only the plan purchase answers with a 402, the price quote you pay and retry, over x402 or MPP (wallet rails settling in USDC) or by card.
- **Credential:** a bearer credential, the agent identity the storefront issues, sent as `Authorization: Bearer <token>`. No upstream API key.
- **Response:** JSON by default, CSV with `as_csv=true`. Fields include `roadTemperature`, `roadCondition` and `delayRisk`.
- **Full purchase flow:** [the buyer skill](https://agents.myradar.dev/zcj/rx03xhjm6q4n/SKILL.md)

## Choose the endpoint

| You need | Endpoint | Time parameter |
| --- | --- | --- |
| Conditions along a trip for a future departure | `GET /v1/timeseries/route` | `depart_time`, `YYYYMMDD.HHMM` |
| An 18 hour forecast at depots, stops or other fixed sites | `GET /v1/timeseries/point` | `itime`, the start time, `YYYYMMDD.HHMM` |
| The same, with a site list too long for a query string | `POST /v1/timeseries/point` | `itime` in the JSON body |
| Past conditions at a list of sites | `GET /v1/timeseries/hist/{begin_time}/{end_time}` | both `YYYYMMDD.HHMM`, in the path |

## Forecast road weather along a route

Calls draw on a plan bought once with an agent credential (Credits starts at $0.02 on a wallet rail, $0.50 by card); [the buyer skill](https://agents.myradar.dev/zcj/rx03xhjm6q4n/SKILL.md) has the purchase steps. `ACCESS_TOKEN` below is the short-lived access token exchanged from the agent credential, as set out in [Identity](https://agents.myradar.dev/zcj/rx03xhjm6q4n/auth.md).

1. Request the route forecast. Encode each query value once:

   ```bash
   curl -sG "https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/route" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-urlencode "origin=41.5,-105.1" \
     --data-urlencode "destination=36.1,-96.1" \
     --data-urlencode "depart_time=20261016.1400"
   ```

   The service looks up driving directions for that departure. The response is a forecast for each step of the trip, matched to the vehicle's expected position, with the fields listed under Read the fields.

2. Read `roadTemperature`, `roadCondition` and `delayRisk` at each step of the response.

## Route options

| Parameter | Effect |
| --- | --- |
| `include_route=true` | Adds the full directions response |
| `as_csv=true` | Returns CSV instead of JSON |
| `saved_route_key` | Reuses a previously saved route |
| `vehicle_heading`, `language`, `instructions_type` | Passed to the directions engine (defaults `-1`, `en-US`, `coded`) |

## Forecast fixed sites and past conditions

For depots and stops, send `latlons` as a JSON array of `[lat, lon]` pairs:

```bash
curl -sG "https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/point" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "latlons=[[41.5,-105.1],[36.1,-96.1]]" \
  --data-urlencode "itime=20261015.1200"
```

The response is the 18 hour road and atmospheric series for each site, starting at `itime`.

For a long site list, send the same fields as a JSON body. `latlons` is a string in this body:

```bash
curl -s -X POST "https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/point" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"latlons": "[[41.5,-105.1],[36.1,-96.1]]", "itime": "20261015.1200", "as_csv": false}'
```

The response is the same as the `GET` form's.

For past conditions, put the window in the path:

```bash
curl -sG "https://agents.myradar.dev/zcj/rx03xhjm6q4n/v1/timeseries/hist/20261001.0000/20261002.0000" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "latlons=[[41.5,-105.1]]"
```

The response is an unbroken series between the two times for each site.

## Read the fields

The route and point series return the same road and atmospheric fields. They come from a 15 minute forecast cycle.

| Field | Contains |
| --- | --- |
| `roadTemperature`, `roadCondition` | Road temperature and road condition |
| `temperature`, `surfaceTemperature` | Air and surface temperature |
| `precipitationRate`, `precipitationType`, `radarPrecipitationRate` | Precipitation rate and type, and radar precipitation |
| `cloudCover`, `solarRadiation`, `snowDepth` | Cloud cover, solar radiation, snow depth |
| `crossWind`, `delayRisk` | Cross wind and delay risk |

## Cost and limits

- Each call is one request. One call costs $0.0002 on Credits. A thousand calls cost $0.20.
- The monthly plans (Starter, Pro, Platinum) charge a base fee and include credit. Their prices are in [the catalog](https://agents.myradar.dev/zcj/rx03xhjm6q4n/manifest.json).
- A plan-funded response carries a `zc-billing` header with `fundingSource`, `chargedUsd` and, when the plan tracks a balance, `remainingCreditUsd`.
- No call is paid on its own. A call without a credential, or without a covering plan, is refused.
- An unpaid purchase 402 charges nothing, so it is safe to stop there.
- The point series covers 18 hours from `itime`. The route series returns the forecast for a future departure time.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No agent credential on the call | Register at [auth.md](https://agents.myradar.dev/zcj/rx03xhjm6q4n/auth.md), then retry with `Authorization: Bearer <token>` |
| `401 invalid_token` | The token expired or did not verify | Exchange your stored assertion for a fresh token |
| `403 plan_required` | No plan covers the call | Buy one from the body's `plans`, then retry |
| `usage_exhausted` | The plan's credit ran out | Top up with `POST https://agents.myradar.dev/zcj/rx03xhjm6q4n/extend` and `amountUsd`, or purchase again |
| `422` | A parameter failed validation | Fix the field named in `detail[].loc` |

The full list is in [the error reference](https://agents.myradar.dev/zcj/rx03xhjm6q4n/errors.md).

## Frequently asked questions

### Does the route forecast show conditions at departure or along the trip?

It shows conditions along the trip. The route endpoint looks up driving directions for `depart_time` and matches each step of the forecast to the vehicle's expected position on the route, returning the same fields as the point series.

### How much does a road weather API call cost?

Each call is one request at $0.02 per 100 requests on Credits, drawn from a balance bought once with an agent credential. On the monthly plans the rate is $0.199 per thousand requests on Starter, $0.133 per thousand requests on Pro and $0.11 per thousand requests on Platinum.

### Can one call cover many depots or stops?

Yes. Put every site in `latlons` on the point time series. Use the `POST` form when the list is too long for a query string.

### Can I get road conditions for a past date?

Yes. Use `GET /v1/timeseries/hist/{begin_time}/{end_time}` with `latlons` for the sites. It returns a continuous series between the two times.

### Is an API key needed?

No. Calls use the bearer credential the storefront issues, sent as `Authorization: Bearer <token>`, and the credential must hold a plan that covers road weather time series.

## Keep reading

- [Buyer skill](https://agents.myradar.dev/zcj/rx03xhjm6q4n/SKILL.md): the full purchase flow
- [How to pay](https://agents.myradar.dev/zcj/rx03xhjm6q4n/payment.md): plans, rails and top-ups
- [Identity](https://agents.myradar.dev/zcj/rx03xhjm6q4n/auth.md): register and exchange an agent credential
- [Road weather time series API reference](https://agents.myradar.dev/zcj/rx03xhjm6q4n/services/timeseries/openapi.json)

---

Updated 2026-10-16. All MyRadar guides: https://agents.myradar.dev/guides.md. Storefront: https://agents.myradar.dev/zcj/rx03xhjm6q4n/llms.txt.