Integrate with ER Buoy and RMWHub

API Introduction

API to allow ropeless gear manufacturers to exchange anonymized data with each other and with regulators.

Base URL

Environment Base URL
Test https://buoy.staging.pamdas.org
Production https://buoy.pamdas.org  

Headers

  • Content-Type: application/json
  • Accept: application/json

 

Get Gear by Location

Returns Gear within 5 nautical miles of the latitude and longitude. 

GET /api/v1.0/gear/

Query Parameters

page integer Page number within the paginated result set.  
page_size integer Number of results per page. 
lat float Include gear within a range of 5 nautical miles from this latitude; latitude must be between -90 and 90. 
lon float Include gear within a range of 5 nautical miles from this longitude; longitude must be between -180 and 180.          
updated_since ISO 8601 datetime Return items updated since the given timestamp.         
state string Filter by state. Use “deployed” for in-water gear or “hauled” for recovered gear.

Example Request

cURL Command

curl -X 'GET' \
  'https://{{site}}/api/v1.0/gear/?lat={{latitude}}&lon={{longitude}}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{your_token}}'

{{site}}: Use the site you have been granted access to.

{{your_token}}:  EarthRanger will provide you with a bearer token to authenticate your requests. This token will  not expire.

 
 

Response Example

API Response

{
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": "7fe3a981-cc6f-4764-8911-693979d647aa",
        "display_id": "1384710e-37ba-44ff-98a7-07c43bb30e59",
        "status": "deployed",
        "devices": [
          {
            "device_id": "3f8c2a7e-6b91-4d2f-9a5c-1e4b8f7c2d6a",
            "source_id": "55e20af5-6a17-4aac-a743-1b3f662a15e6",
            "label": "a",
            "location": {
              "latitude": 20.586871,
              "longitude": -103.427398
            },
            "last_updated": "2025-11-15T22:06:31.426000-08:00",
            "last_deployed": "2025-11-16T06:06:31.899346+00:00"
          },
          {
            "device_id": "3f8c2a7e-6b91-4d2f-9a5c-1e4b8f7c2d6b",
            "source_id": "d100badb-86ed-4924-8e06-4ba4ff6de091",
            "label": "b",
            "location": {
              "latitude": 20.599692,
              "longitude": -103.42115
            },
            "last_updated": "2025-11-15T22:07:54.526000-08:00",
            "last_deployed": "2025-11-16T06:07:54.954513+00:00"
          }
        ],
        "type": "trawl",
        "manufacturer": "DAS",
        "last_updated": "2025-11-16T06:06:31.838517+00:00"
      }
    ]
  },
  "status": {
    "code": 200,
    "message": "OK"
  }
}
 
 

 

Get Gear by ID

Returns a single trawl with a matching ID

GET /api/v1.0/gear/{id}

Example Request

cURL Command

Basic request:

curl -X 'GET' \
  'https://{{site}}/api/v1.0/gear/{{your_gear_id}}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{your_token}}'

{{site}}: Use the site you have been granted access to.

{{your_token}}:  EarthRanger will provide you with a bearer token to authenticate your requests. This token will  not expire.

 
 

Example Response

API Response

{
  "id": "7fe3a981-cc6f-4764-8911-693979d647aa",
  "display_id": "1384710e-37ba-44ff-98a7-07c43bb30e59",
  "status": "deployed",
  "devices": [
    {
      "device_id": "Test_1396b-d092-71ae",
      "source_id": "55e20af5-6a17-4aac-a743-1b3f662a15e6",
      "label": "a",
      "location": {
        "latitude": 20.586871,
        "longitude": -103.427398
      },
      "last_updated": "2025-11-15T22:06:31.426000-08:00",
      "last_deployed": "2025-11-16T06:06:31.899346+00:00"
    },
    {
      "device_id": "Test_02a34-43d6-add7",
      "source_id": "d100badb-86ed-4924-8e06-4ba4ff6de091",
      "label": "b",
      "location": {
        "latitude": 20.599692,
        "longitude": -103.42115
      },
      "last_updated": "2025-11-15T22:07:54.526000-08:00",
      "last_deployed": "2025-11-16T06:07:54.954513+00:00"
    }
  ],
  "type": "trawl",
  "manufacturer": "DAS",
  "last_updated": "2025-11-16T06:06:31.838517+00:00"
}
 
 

 

Submit Gear Location

This API allows users to submit a single trawl with either single or multiple devices.  

POST /api/v1.0/gear/

I. Trawl Information 

Field

Allowed Values

Required

Notes

set_id

RFC-4122 UUIDs

No* 

Unique identifier for the gear set. If omitted, inferred from mfr_set_id or the provided devices

 

Important: 

  • The request needs to include set_id or mfr_set_id.
  • set_id must be valid RFC-4122 UUIDs. 
  • set_id can't be reused across trawl deployment. 

mfr_set_id

 string (max 100)

No* 

Manufacturer's string reference for the gear set. Defaults to set_id if not provided.

 

Important: 

The request needs to include set_id or mfr_set_id.

deployment_type

 trawl, single, surface

Yes 

Type of deployment for this set. 

initial_deployment_date

ISO 8601 datetime

Yes *

Required when creating a new gear set for the first time. 

 

Important: 

Not required for updates.

manufacturer_name

Existing identifier defined by EarthRanger.

Yes 

Identifies the manufacturer. Will be provided by EarthRanger

devices

array<gear>

Yes

Gear that is part of the set. Can be single or multiple. See table below.

 

Example:
"devices": [
 {
   "device_id": "b1b2c3d4-0002-0002-0002-000000000001",
   "last_deployed": "2025-12-30T21:34:19+00:00",

   "last_updated": "2025-12-30T21:34:19+00:00",
   "device_status": "deployed",
   "location": {
     "latitude": 20.622157,
     "longitude": -103.471536
   }
 }
]

Optional Fields (click to expand)

Field

Allowed Values

Notes

set_additional_data

JSON object

Freeform key-value data about the gear set (e.g. vessel name, trip info).

 

Example:

{
 "notes": "Deployed in rocky area",
 "custom_field2": 42
}

 

last_updated

 ISO 8601 datetime

Timestamp of the last update to the gear set, as reported by the manufacturer.
 
 

II. Gear Information

Property

Allowed Values

Required

Notes

device_id

UUID

Yes 

 Unique identifier for the device. Used as the primary key in the system.

mfr_device_id

string (max 100)

No* 

Serial Number.

Manufacturer's own string reference for the device. Defaults to device_id if not provided.

 

Important: 

mfr_device_id is used for display purposes in the platform UI.

If mfr_device_id is not provided, the set_id will be displayed instead.

last_deployed

ISO 8601 datetime

Yes 

Timestamp when the device was last deployed. Cannot be in the future.

last_updated

 ISO 8601 datetime

Yes 

Timestamp of the last update to this device. Cannot be in the future.

device_status

deployed, hauled, lost

Yes 

Current state of the device. Drives gear set active/inactive logic.

 

Important: 

When hauling, it's important to use the same set_id and device_id as the request sent to deploy.

location

Latitude: -90 to 90

Longitude: -180 to 180

Yes

Deployed latitude and longitude

{
 "latitude": 10.4,
 "longitude": 40.24
}

Optional Fields (click to expand)

Property

Allowed Values

Notes

positioning_type

gps, acoustic

 How the device determines its position. Defaults to gps.

release_type

timed, acoustic, galvanic

 The mechanism used to release the device.

device_additional_data

JSON object

Freeform key-value data about the device (e.g. battery level, firmware version). Stored but not actively processed.

 

{
 "notes": "Deployed in rocky area",
 "custom_field1": "value1",
 "custom_field2": 42
}
 
 

Example Request

Python

import requests                                                                                                                                           
                  
  url = "https://<site>/api/v1.0/gear"                                                                                                                      
                  
  headers = {
      "Authorization": "Bearer <your_token>",
      "Content-Type": "application/json",
  }

  payload = {
      "deployment_type": "trawl",
      "manufacturer_name": "<identifier provided by our team>",
      "set_id": "a1b2c3d4-0001-0001-0001-000000000001",
      "devices_in_set": 2,
      "initial_deployment_date": "2025-12-30T21:34:19+00:00",
      "devices": [
          {
              "device_id": "b1b2c3d4-0002-0002-0002-000000000001",
              "last_deployed": "2025-12-30T21:34:19+00:00",
              "last_updated": "2025-12-30T21:34:19+00:00",
              "device_status": "deployed",
              "release_type": "acoustic",
              "location": {
                  "latitude": 20.622157,
                  "longitude": -103.471536,
              },
          },
          {
              "device_id": "b1b2c3d4-0002-0002-0002-000000000002",
              "last_deployed": "2025-12-30T21:34:27+00:00",
              "last_updated": "2025-12-30T21:34:27+00:00",
              "device_status": "deployed",
              "release_type": "acoustic",
              "location": {
                  "latitude": 20.622158,
                  "longitude": -103.471537,
              },
              "device_additional_data": {
                  "sequence": 2,
                  "serial_number": "SN-00123",
                  "battery_pct": 85,
              },
          },
      ],
  }
 
 

cURL Command

curl --location 'https://{{site}}/api/v1.0/gear' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your token>' \
--data '{
  "deployment_type": "trawl",
  "manufacturer_name": "<identifier provided by our team>",
  "set_id": "<single-use UUID>",
  "devices_in_set": 2,
  "devices": [
    {
      "device_id": "<UUID>",
      "last_deployed": "2025-12-30T21:34:19+00:00",
      "last_updated": "2025-12-30T21:34:19+00:00",
      "device_status": "deployed",
      "location": {
        "latitude": 20.622157, 
        "longitude": -103.471536
      },
      "release_type": "acoustic"
    },
    {
      "device_id": "<UUID>",
      "last_deployed": "2025-12-30T21:34:27+00:00",
      "last_updated": "2025-12-30T21:34:27+00:00",
      "device_status": "deployed",
      "location": {
        "latitude": 20.622158, 
        "longitude": -103.471537
      }
    }
  ],
  "initial_deployment_date": "2025-12-30T21:34:19+00:00"
}
'
 
 

Example Response

API Response

{
    "data": {
        "detail": "Gears successfully processed",
        "set_id": "cf94d09d-b2b5-43cf-be2b-40f8d663b22f"
    },
    "status": {
        "code": 201,
        "message": "Created"
    }
}
 
 

 

 

 

Changelog

  • March 4, 2026. Removed optional fields not actually in use.

 

 

 

Mar 4, 2026