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

# Quickstart

> Make your first Buoy API call in under 5 minutes.

## Prerequisites

You need an API key. If you don't have one yet, see [Authentication](/authentication) to request access.

## Step 1 — List active buoys

Fetch a paginated list of active buoys. Each buoy includes its latest reading — no follow-up call needed.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.thebuoy.app/v2/buoys?per_page=5"
  ```

  ```python Python theme={null}
  import requests

  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  r = requests.get(
      "https://api.thebuoy.app/v2/buoys",
      params={"per_page": 5},
      headers=headers,
  )
  r.raise_for_status()
  print(r.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.thebuoy.app/v2/buoys?per_page=5",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "data": {
    "buoys": [
      {
        "id": 12,
        "name": "Anglet",
        "lat": 43.4832,
        "lng": -1.5586,
        "source": "Candhis",
        "source_identifier": "64002",
        "slug": "anglet",
        "last_reading_time": "2026-03-27T08:00:00Z",
        "readings_count": 142300,
        "last_reading": {
          "significient_height": 1.8,
          "maximum_height": 2.4,
          "period": 9.5,
          "direction": 285,
          "water_temperature": 14.2,
          "time": "2026-03-27T08:00:00Z"
        },
        "timezone": "Europe/Paris"
      }
    ],
    "count": 312
  },
  "meta": {
    "page": 1,
    "per_page": 5,
    "total_pages": 63,
    "timestamp": "2026-03-27T09:00:00Z"
  }
}
```

## Step 2 — Filter by country

To get all active buoys in a specific country, pass the ISO 3166-1 alpha-2 country code.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys?country=FR"
```

Use this to bootstrap a cron job over all French buoys. See the [Country Buoys guide](/guides/country-buoys) for a complete pattern.

## Step 3 — Get targeted last readings

If you already know the IDs of the buoys you care about, use `last_readings` to fetch only those — up to 100 at a time:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys/last_readings?ids=12,45,78&limit=3"
```

**Response:**

```json theme={null}
{
  "status": "success",
  "data": {
    "buoys": [
      {
        "id": 12,
        "name": "Anglet",
        "lat": 43.4832,
        "lng": -1.5586,
        "source": "Candhis",
        "last_reading": {
          "significient_height": 1.8,
          "maximum_height": 2.4,
          "period": 9.5,
          "direction": 285,
          "water_temperature": 14.2,
          "time": "2026-03-27T08:00:00Z"
        }
      }
    ],
    "missing_ids": []
  },
  "meta": {
    "timestamp": "2026-03-27T09:00:00Z"
  }
}
```

## Step 4 — Find the nearest buoy

No IDs? Find the closest buoy to any coordinates:

```bash theme={null}
curl "https://api.thebuoy.app/v2/buoys/nearest?lat=43.48&lng=-1.56&max_distance=50"
```

<Note>
  `nearest` and `search` are public endpoints — no API key required.
</Note>

## What's next?

<CardGroup cols={2}>
  <Card title="Country Buoys" icon="location-dot" href="/guides/country-buoys">
    Full cron job pattern for collecting all readings from a country.
  </Card>

  <Card title="Last Readings" icon="clock" href="/guides/last-readings">
    Efficiently poll specific buoys with the bulk readings endpoint.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Plan your request budget and handle 429 responses.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full endpoint documentation with interactive playground.
  </Card>
</CardGroup>