> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Weather Alerts

> List the weather watches, warnings and advisories active at a US point, including those issued but not yet begun.

List the weather watches, warnings and advisories in force now at a point in the United States, given its latitude and longitude. Use it to check whether a storm, flood, heat, fire-weather or winter-weather alert covers a property, a route stop or a claim location today. Alerts are ordered most severe first (Extreme, Severe, Moderate, Minor, Unknown), then by soonest to expire. The source's active list is returned as it gives it: an alert already issued whose event has not begun (a watch for tomorrow, urgency Future, `onset_at` in the future) is included, so check `urgency` and `onset_at` to tell what is under way from what is coming. `total` is the number of alerts returned. Expired and past alerts are not returned. A point with nothing active is a completed result with `total` 0.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="latitude" type="number" required>
  Latitude in decimal degrees, 17 to 72, for example 29.7604. From 17 to 72.
</ParamField>

<ParamField body="longitude" type="number" required>
  Longitude in decimal degrees, -180 to -64 (west is negative), for example -95.3698. From -180 to -64.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `place_weather_alerts`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Weather Service`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="number">
  Number of alerts returned: those active at the point, including issued alerts whose event has not begun.
</ResponseField>

<ResponseField name="data.result.alerts" type="object[]">
  Alerts.
</ResponseField>

<ResponseField name="data.result.alerts[].event" type="string">
  The alert type, for example Flood Warning or Winter Weather Advisory. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].severity" type="string">
  Extreme, Severe, Moderate, Minor or Unknown. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].certainty" type="string">
  Observed, Likely, Possible, Unlikely or Unknown. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].urgency" type="string">
  Immediate, Expected, Future, Past or Unknown. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].headline" type="string">
  Headline. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].description" type="string">
  Description. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].instruction" type="string">
  What the issuer advises people to do; null when none is given.
</ResponseField>

<ResponseField name="data.result.alerts[].area" type="string">
  The area the alert covers, as the issuer names it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].sender" type="string">
  The issuing forecast office, for example NWS Lake Charles LA. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].effective_at" type="string">
  ISO 8601, as the source gives it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].onset_at" type="string">
  ISO 8601, as the source gives it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].expires_at" type="string">
  ISO 8601, as the source gives it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.alerts[].ends_at" type="string">
  ISO 8601, as the source gives it; null when the event has no set end.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-weather-alerts \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "latitude": 30.1487,
      "longitude": -94.0188
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/place-weather-alerts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "latitude": 30.1487,
      "longitude": -94.0188
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/place-weather-alerts', {
    latitude: 30.1487,
    longitude: -94.0188
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "place_weather_alerts",
      "result": {
        "total": 1,
        "alerts": [
          {
            "event": "Flood Warning",
            "severity": "Severe",
            "certainty": "Observed",
            "urgency": "Immediate",
            "headline": "Flood Warning issued October 12 at 10:35AM CDT by NWS Lake Charles LA",
            "description": "The Flood Warning is extended for the following rivers.",
            "instruction": "Turn around, do not drown when encountering flooded roads.",
            "area": "Hardin, TX; Jasper, TX; Jefferson, TX; Orange, TX",
            "sender": "NWS Lake Charles LA",
            "effective_at": "2026-10-12T10:35:00-05:00",
            "onset_at": "2026-10-12T10:35:00-05:00",
            "expires_at": "2026-10-13T01:00:00-05:00",
            "ends_at": null
          }
        ]
      },
      "evidence": {
        "source": "US National Weather Service",
        "source_kind": "public",
        "retrieved_at": "2026-01-15T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.002 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.