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

# Earthquakes

> List the earthquakes recorded near a point since a date, newest first, with magnitude, depth and felt reports.

List the earthquakes recorded within a distance of a point, given its latitude and longitude. Use it to check the seismic history around a property, a facility or a route stop. Earthquakes are returned newest first, each with its magnitude, depth in kilometres, how many people reported feeling it (`felt_reports`, null when nobody was asked or none reported) and whether a tsunami was flagged. By default it looks back 30 days within 100 km for magnitude 2.5 and above; `since` and `until` (YYYY-MM-DD, UTC) set the dates, `radius_km` the distance (1 to 500), `min_magnitude` the floor and `limit` the most returned (1 to 50). Events the source records as something other than an earthquake, such as quarry blasts, are left out. A point with no earthquake in range is a completed result with an empty list.

## Authentication

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

## Request Body

<ParamField body="latitude" type="number" required>
  Latitude in decimal degrees, -90 to 90, for example 37.77. From -90 to 90.
</ParamField>

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

<ParamField body="radius_km" type="number">
  Distance from the point in kilometres, 1 to 500; default 100. From 1 to 500. Defaults to `100`.
</ParamField>

<ParamField body="since" type="string">
  Earliest date, YYYY-MM-DD (UTC); default 30 days before the call. Use YYYY-MM-DD.
</ParamField>

<ParamField body="until" type="string">
  Latest date, YYYY-MM-DD (UTC); default now. Use YYYY-MM-DD.
</ParamField>

<ParamField body="min_magnitude" type="number">
  Smallest magnitude to return, 0 to 10; default 2.5. From 0 to 10. Defaults to `2.5`.
</ParamField>

<ParamField body="limit" type="integer">
  Most earthquakes to return, 1 to 50; default 10. From 1 to 50. Defaults to `10`.
</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_earthquakes`
</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 Geological Survey`.
</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.earthquakes" type="object[]">
  Earthquakes.
</ResponseField>

<ResponseField name="data.result.earthquakes[].id" type="string">
  The source's event id. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].magnitude" type="number">
  Magnitude. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].magnitude_type" type="string">
  How the magnitude was measured, for example md or mw. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].place" type="string">
  The nearest named place, as the source words it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].occurred_at" type="string">
  ISO 8601, UTC. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].latitude" type="number">
  Latitude. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].longitude" type="number">
  Longitude. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].depth_km" type="number">
  Depth below the surface in kilometres. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.earthquakes[].felt_reports" type="number">
  Number of people who reported feeling it; null when none were collected.
</ResponseField>

<ResponseField name="data.result.earthquakes[].alert" type="string">
  The source's impact alert level (green, yellow, orange, red); null when none was issued.
</ResponseField>

<ResponseField name="data.result.earthquakes[].tsunami" type="boolean">
  True when the source flagged a tsunami.
</ResponseField>

<ResponseField name="data.result.earthquakes[].url" type="string">
  The source's page for the event. `null` when the source gives no value.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-earthquakes \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "latitude": 37.77,
      "longitude": -122.42,
      "radius_km": 100,
      "since": "2026-07-01",
      "min_magnitude": 2.5,
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/place-earthquakes", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "latitude": 37.77,
      "longitude": -122.42,
      "radius_km": 100,
      "since": "2026-07-01",
      "min_magnitude": 2.5,
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/place-earthquakes', {
    latitude: 37.77,
    longitude: -122.42,
    radius_km: 100,
    since: '2026-07-01',
    min_magnitude: 2.5,
    limit: 1
  });
  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_earthquakes",
      "result": {
        "earthquakes": [
          {
            "id": "nc75444432",
            "magnitude": 2.51,
            "magnitude_type": "md",
            "place": "5 km W of Yountville, CA",
            "occurred_at": "2026-09-29T16:06:37.440Z",
            "latitude": 38.3978333333333,
            "longitude": -122.4235,
            "depth_km": 7.89,
            "felt_reports": 51,
            "alert": null,
            "tsunami": false,
            "url": "https://earthquake.usgs.gov/earthquakes/eventpage/nc75444432"
          }
        ]
      },
      "evidence": {
        "source": "US Geological Survey",
        "source_kind": "public",
        "retrieved_at": "2026-01-15T12:00:00.000Z",
        "as_of": "2026-10-13T07:33:40.000Z"
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 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.