> ## 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.

# Tropical Cyclones

> List active tropical cyclones and their official forecast tracks, optionally near a point.

Lists active storms and official forecast points in the Atlantic and eastern/central North Pacific. Source fields are observed; movement\_kt, distance\_km, closest\_approach\_km and closest\_approach\_at are derived. Empty storms with coverage.covered true means looked, saw nothing matching; false means no evidence either way. Coverage names watched basins and latest advisory time. West Pacific and Indian Ocean are unwatched.

## Authentication

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

## Request Body

**latitude** `number`

Latitude in decimal degrees; give longitude too. From -90 to 90.

**longitude** `number`

Longitude in decimal degrees; west is negative. From -180 to 180.

**radius\_km** `number`

Maximum current or forecast distance from the point in kilometres. From 1 to 2000. Defaults to `500`.

**basin** `string`

Basin to list; omitted means all three watched basins. One of `atlantic`, `east_pacific`, `central_pacific`.

**limit** `integer`

Maximum storms to return. From 1 to 200. Defaults to `25`.

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

## Response (200 OK)

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

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `place_tropical_cyclones`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US National Hurricane Center`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

Latest issued\_at in the active storm feed; null when there are no active advisories.

## Result

Nested under `data.result`.

**data.result.coverage** `object`

Coverage.

**data.result.coverage.covered** `boolean`

Covered.

**data.result.coverage.basins** `string[]`

Basins.

**data.result.coverage.latest\_advisory\_at** `string | null`

Latest advisory at. `null` when the source gives no value.

**data.result.total** `integer`

Total.

**data.result.returned** `integer`

Returned.

**data.result.truncated** `boolean`

Truncated.

**data.result.storms** `object[]`

Storms.

**data.result.storms\[].observed** `object`

Observed.

**data.result.storms\[].observed.id** `string`

Id.

**data.result.storms\[].observed.name** `string`

Name.

**data.result.storms\[].observed.classification** `string`

Classification.

**data.result.storms\[].observed.intensity\_kt** `number | null`

Intensity kt. `null` when the source gives no value.

**data.result.storms\[].observed.pressure\_mb** `number | null`

Pressure mb. `null` when the source gives no value.

**data.result.storms\[].observed.latitude** `number`

Latitude.

**data.result.storms\[].observed.longitude** `number`

Longitude.

**data.result.storms\[].observed.movement\_deg** `number | null`

Movement deg. `null` when the source gives no value.

**data.result.storms\[].observed.movement\_mph** `number | null`

Movement mph. `null` when the source gives no value.

**data.result.storms\[].observed.position\_at** `string`

Position at.

**data.result.storms\[].observed.advisory\_number** `string`

Advisory number.

**data.result.storms\[].observed.issued\_at** `string`

Issued at.

**data.result.storms\[].observed.advisory\_url** `string | null`

Advisory url. `null` when the source gives no value.

**data.result.storms\[].observed.forecast** `object[]`

Forecast.

**data.result.storms\[].observed.forecast\[].valid\_at** `string`

Valid at.

**data.result.storms\[].observed.forecast\[].latitude** `number`

Latitude.

**data.result.storms\[].observed.forecast\[].longitude** `number`

Longitude.

**data.result.storms\[].observed.forecast\[].max\_wind\_kt** `number | null`

Max wind kt. `null` when the source gives no value.

**data.result.storms\[].derived** `object`

Derived.

**data.result.storms\[].derived.movement\_kt** `object`

Movement kt.

**data.result.storms\[].derived.movement\_kt.value** `number | null`

Value. `null` when the source gives no value.

**data.result.storms\[].derived.movement\_kt.rule** `string`

Rule.

**data.result.storms\[].derived.movement\_kt.from** `string[]`

From.

**data.result.storms\[].derived.distance\_km** `object`

Distance km.

**data.result.storms\[].derived.distance\_km.value** `number | null`

Value. `null` when the source gives no value.

**data.result.storms\[].derived.distance\_km.rule** `string`

Rule.

**data.result.storms\[].derived.distance\_km.from** `string[]`

From.

**data.result.storms\[].derived.closest\_approach\_km** `object`

Closest approach km.

**data.result.storms\[].derived.closest\_approach\_km.value** `number | null`

Value. `null` when the source gives no value.

**data.result.storms\[].derived.closest\_approach\_km.rule** `string`

Rule.

**data.result.storms\[].derived.closest\_approach\_km.from** `string[]`

From.

**data.result.storms\[].derived.closest\_approach\_at** `object`

Closest approach at.

**data.result.storms\[].derived.closest\_approach\_at.value** `string | null`

Value. `null` when the source gives no value.

**data.result.storms\[].derived.closest\_approach\_at.rule** `string`

Rule.

**data.result.storms\[].derived.closest\_approach\_at.from** `string[]`

From.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-tropical-cyclones \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "limit": 10
  }'
```

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

```typescript SDK theme={null}
const result = await agent.tool('lookup/place-tropical-cyclones', {
  limit: 10
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "place_tropical_cyclones",
    "result": {
      "coverage": {
        "covered": true,
        "basins": [
          "atlantic",
          "east_pacific",
          "central_pacific"
        ],
        "latest_advisory_at": null
      },
      "total": 0,
      "returned": 0,
      "truncated": false,
      "storms": []
    },
    "evidence": {
      "source": "US National Hurricane Center",
      "source_kind": "public",
      "retrieved_at": "2026-10-28T04:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-28T04:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* All inputs are optional. With no point, lists all active storms; basin can narrow the list. Limit defaults to 25, at most 200.
* Derived movement\_kt converts observed movement\_mph to knots; distance\_km is a great-circle distance. Each derived value names its rule and input fields.
* Point coverage uses the northern hemisphere from the date line east to 20E, including coastal and inland sites. Coverage does not extend to the other hemisphere or other basins when a radius crosses the boundary.
* Closest approach uses shortest great-circle segments with time interpolated between official points, starting at the current position. It is a forecast, not a measured impact or wind footprint. The uncertainty cone is omitted.
* The latest advisory and forecast must match. Missing or incomplete forecast data fails the lookup instead of implying there are no nearby storms.
* NWS public-data terms apply: [https://www.weather.gov/disclaimer](https://www.weather.gov/disclaimer). No endorsement is implied.
* 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.