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

# API Reference

> Complete reference for the Data Docked Maritime API

## Download API Specs

<CardGroup cols={2}>
  <Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
    Download OpenAPI 3.1 JSON schema
  </Card>

  <Card title="Postman Collection" icon="rocket" href="/api-reference/postman-collection.json">
    Import directly into Postman
  </Card>
</CardGroup>

***

## Base URL

```
https://datadocked.com/api/vessels_operations
```

## Authentication

All requests require an API key in the `x-api-key` header.

```bash theme={null}
curl -X GET "https://datadocked.com/api/vessels_operations/get-vessel-location?imo_or_mmsi=9247431" \
  -H "x-api-key: YOUR_API_KEY"
```

<Card title="Get your API key" icon="key" href="https://datadocked.com/signup">
  Sign up for free to get your API key
</Card>

***

## Endpoints Overview

<CardGroup cols={2}>
  <Card title="Account" icon="user" href="/api-reference/account/my-credits">
    Check credit balance
  </Card>

  <Card title="Vessel Tracking" icon="location-dot" href="/api-reference/vessel/get-vessel-location">
    Real-time vessel positions
  </Card>

  <Card title="Vessel Details" icon="ship" href="/api-reference/vessel/get-vessel-info">
    Specifications and management
  </Card>

  <Card title="Port Operations" icon="anchor" href="/api-reference/port/port-calls-by-vessel">
    Port calls and traffic
  </Card>
</CardGroup>

***

## Quick Examples

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # Get vessel location
    curl "https://datadocked.com/api/vessels_operations/get-vessel-location?imo_or_mmsi=9247431" \
      -H "x-api-key: YOUR_API_KEY"

    # Check credits
    curl "https://datadocked.com/api/vessels_operations/my-credits" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    headers = {"x-api-key": "YOUR_API_KEY"}
    base = "https://datadocked.com/api/vessels_operations"

    # Get vessel location
    resp = requests.get(f"{base}/get-vessel-location",
                       params={"imo_or_mmsi": "9247431"},
                       headers=headers)
    vessel = resp.json()["detail"]
    print(f"{vessel['name']}: {vessel['latitude']}, {vessel['longitude']}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const API_KEY = 'YOUR_API_KEY';
    const BASE = 'https://datadocked.com/api/vessels_operations';

    // Get vessel location
    const resp = await fetch(`${BASE}/get-vessel-location?imo_or_mmsi=9247431`, {
      headers: { 'x-api-key': API_KEY }
    });
    const { detail } = await resp.json();
    console.log(`${detail.name}: ${detail.latitude}, ${detail.longitude}`);
    ```
  </Tab>
</Tabs>

***

## Credit Costs

| Endpoint                   | Credits      |
| -------------------------- | ------------ |
| My Credits                 | 0            |
| Get Vessel Location        | 1            |
| Get Vessel Particulars     | 1            |
| Get Vessel Engine Data     | 1            |
| Get Vessel Management Data | 1            |
| Vessel Details by Name     | 1            |
| Vessel Weather Data        | 1            |
| Port Calls by Vessel       | 1            |
| Vessel Inspection Data     | 3            |
| Get Vessel Info            | 5            |
| Get Vessels by Area        | 10           |
| Port Calls by Port         | 50           |
| Bulk Location Search       | 1 per vessel |
| Historical Data            | 5 per date   |

***

## Response Format

All responses return JSON with data in the `detail` field:

```json theme={null}
{
  "detail": {
    "name": "EVER GIVEN",
    "imo": "9811000",
    "mmsi": "353136000",
    "latitude": "31.234567",
    "longitude": "32.345678",
    "speed": "12.5",
    "course": "180",
    "destination": "ROTTERDAM"
  }
}
```

***

## Error Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 400  | Bad request - Invalid parameters          |
| 401  | Unauthorized - Invalid or missing API key |
| 404  | Not found - Vessel or resource not found  |
| 429  | Too many requests - Rate limit exceeded   |
| 500  | Server error                              |

Error response format:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

***

## Identifiers

### IMO Number

A 7-digit unique identifier assigned to ships by the International Maritime Organization.

### MMSI

A 9-digit Maritime Mobile Service Identity used for radio communication.

Most endpoints accept either IMO or MMSI in the `imo_or_mmsi` parameter.

***

## Data Sources

| Source          | Coverage       | Endpoints                           |
| --------------- | -------------- | ----------------------------------- |
| Terrestrial AIS | Coastal waters | All endpoints                       |
| Satellite AIS   | Global         | Real-time location, Historical data |

The `dataSource` field in responses indicates whether data came from terrestrial or satellite receivers.