# Get a weather forecast by latitude and longitude with MyRadar's API

MyRadar's forecast API returns, for a single latitude and longitude point, current conditions, minute by minute precipitation for the next hour, an hourly forecast for 48 or 168 hours, a daily forecast and severe weather alerts. The minutely section and the alerts cover the US only, and the response uses the same shape as the former Dark Sky API. Each call is one `GET https://agents.myradar.dev/zcj/mah1upwlz8yg/v1/forecast/{point}` request drawn from your plan at $0.02 per 100 requests, sent with `Authorization: Bearer <token>` for an agent credential that holds a plan.

## At a glance

- **Endpoint:** `GET https://agents.myradar.dev/zcj/mah1upwlz8yg/v1/forecast/{point}`, where `point` is `lat,lon` in degrees with no space, such as `45.51,-122.68`
- **Query:** `units` (`us`, `si`, `ca`, `uk2`), `exclude` (comma separated sections), `extend=hourly` (168 hours), `lang` (`en` only)
- **Price:** one request per call, $0.02 per 100 requests. The Starter, Pro and Platinum monthly plans have their own rates, listed in the [catalog](https://agents.myradar.dev/zcj/mah1upwlz8yg/manifest.json) and compared in [Pricing](/guides/pricing).
- **Payment:** buy a plan once with an agent credential; calls draw on it and never answer with a 402.
- **Response:** JSON with `latitude`, `longitude`, `timezone`, `currently`, `minutely`, `hourly`, `daily`, `alerts` and `flags`
- **Limits:** one point per request. `minutely` and `alerts` cover the US only.
- **Full purchase flow:** [the buyer skill](https://agents.myradar.dev/zcj/mah1upwlz8yg/SKILL.md)

## Get a forecast for a point

1. Get an agent credential and a plan, once. [auth.md](https://agents.myradar.dev/zcj/mah1upwlz8yg/auth.md) registers a credential, and Credits start at $0.02, or $0.50 by card, as [the buyer skill](https://agents.myradar.dev/zcj/mah1upwlz8yg/SKILL.md) sets out. If you already hold a credential, `GET https://agents.myradar.dev/zcj/mah1upwlz8yg/agent/entitlements` with your bearer lists what it owns before you buy again.

2. Request the forecast with the same bearer:

   ```bash
   curl -s "https://agents.myradar.dev/zcj/mah1upwlz8yg/v1/forecast/38.8977,-77.0365?units=us&exclude=minutely" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The response is a JSON object with this shape:

   ```text
   {
     "latitude": number, "longitude": number, "timezone": string,
     "currently": { "time", "summary", "icon", "temperature", "apparentTemperature",
                    "precipIntensity", "precipProbability", "precipType", "dewPoint",
                    "humidity", "pressure", "windSpeed", "windGust", "windBearing",
                    "cloudCover", "visibility", "uvIndex", "ozone" },
     "hourly": { "summary", "icon", "data": [ { same fields as currently } ] },
     "daily":  { "summary", "icon", "data": [ { "time", "summary", "icon",
                 "temperatureHigh", "temperatureLow", "temperatureMin", "temperatureMax",
                 "sunriseTime", "sunsetTime", "moonPhase", "precipProbability", ... } ] },
     "flags":  { "units": string }
   }
   ```

   In the example response, `hourly.data` holds 49 entries and `daily.data` holds 11. The example call took 0.9 seconds and drew $0.0002 from Credits, as its `zc-billing` header reported, for one request at $0.02 per 100 requests.

3. Read the sections you asked for. Every `time` is a UNIX time: hourly entries align to the top of the hour and daily entries to midnight. `timezone` names the location's timezone. `icon` is one of `clear-day`, `clear-night`, `rain`, `snow`, `sleet`, `wind`, `fog`, `cloudy`, `partly-cloudy-day` and `partly-cloudy-night`. `precipProbability`, `humidity` and `cloudCover` run from 0 to 1. `alerts` is an array of active alerts for the point, if any, each with `title`, `severity` (`Advisory`, `Watch` or `Warning`), `time`, `expires` and `description`.

## Choose units and sections

| You need | Set |
| --- | --- |
| Imperial units (the default) | `units=us` |
| SI units | `units=si` |
| SI with wind in km/h | `units=ca` |
| SI with wind in mph and visibility in miles | `units=uk2` |
| 168 hours of hourly forecast instead of 48 | `extend=hourly` |
| Current conditions only | `exclude=minutely,hourly,daily,alerts,flags` |
| Hourly and daily only | `exclude=currently,minutely,alerts` |
| A point outside the US | `exclude=minutely,alerts` |

`exclude` leaves sections out of the response. It does not change the price: each call is one request whatever it returns, so ask only for what you read.

## What is charged and when

- Buying a plan is the only payment. The forecast call itself never answers with a 402.
- Each forecast call draws one request from your plan. 100 forecast calls draw $0.02 on Credits.
- A plan-funded response carries a `zc-billing` header with `fundingSource`, `chargedUsd` and `remainingCreditUsd`.
- The endpoint takes one point. Several locations are several requests.
- `lang` accepts `en` only.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call carried no agent credential | Register at [auth.md](https://agents.myradar.dev/zcj/mah1upwlz8yg/auth.md) and retry with `Authorization: Bearer <token>` |
| `401 invalid_token` (`token_expired`) | The access token expired | Exchange the stored assertion for a fresh token and retry |
| `403 plan_required` | The credential holds no plan covering the forecast | Buy one of the plans the body lists, then retry |
| Error code `usage_exhausted` | A call found the Credits balance used up | Top up with `POST https://agents.myradar.dev/zcj/mah1upwlz8yg/extend` and `{"amountUsd": "<amount>"}`, then retry the call |
| MyRadar's own status and body | The storefront forwarded the call and MyRadar rejected the request | Fix the path or query against the [API reference](https://agents.myradar.dev/zcj/mah1upwlz8yg/services/forecast/openapi.json) and retry |

## Frequently asked questions

### Does the minute by minute rain forecast work outside the US?

No. The `minutely` section, covering the next 60 minutes, and the `alerts` section are US only. For other points, exclude them and read `currently`, `hourly` and `daily`.

### Does excluding sections make a forecast call cheaper?

No. Every call is one request at $0.02 per 100 requests on Credits, whatever sections it returns. `exclude` makes the response smaller, not cheaper.

### How do I get 168 hours of hourly forecast?

Add `extend=hourly`. The `hourly` section then covers the next 168 hours instead of 48, in the same call and at the same one-request price.

### Can I get forecasts for several locations in one call?

No. The path takes one `lat,lon` point. Send one request per location, and each draws one request from your plan.

### Which plan should I use for a weather forecast API?

Credits suits small or uneven volumes: you prepay a balance and each call draws it down. The Starter, Pro and Platinum monthly plans bill requests at their own rates; [Pricing](/guides/pricing) compares them by volume.

## Keep reading

- [Switch from Dark Sky to MyRadar's forecast API](/guides/replace-dark-sky-api)
- [Check severe weather alerts for a point or area](/guides/severe-weather-alerts)
- [MyRadar weather API pricing](/guides/pricing)
- [MyRadar API errors and recovery](/guides/errors)
- [The buyer skill](https://agents.myradar.dev/zcj/mah1upwlz8yg/SKILL.md): the full purchase flow
- [Identity](https://agents.myradar.dev/zcj/mah1upwlz8yg/auth.md): register and refresh an agent credential

---

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