Integrate with ER Buoy and RMWHub

1. API Introduction

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

Base URL

United States

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

 

Canada

Environment Base URL
Production https://dfo.pamdas.org  

Headers

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

 

2. Changelog

  • April 9, 2026. Included a new section (“Redeploying gear in a new trawl set”).
  • April 9, 2026. Description for new rules affecting last_deployed and last_updated.
  • March 4, 2026. Removed optional fields not actually in use.

 

3. 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 --location '{{site}}/api/v1.0/gear?state=deployed&lat={{latitude}}&lon={{longitude}}' \
--header '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": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": "6b5ac585-76fe-4af8-9813-f6f56a2c6c32",
                "display_id": "6b5ac585-76fe-4af8-9813-f6f56a2c6c32",
                "status": "deployed",
                "devices": [
                    {
                        "device_id": "fe5b4705-0b36-422c-846b-620d4aae983b",
                        "mfr_device_id": "buoy001",
                        "label": "a",
                        "location": {
                            "latitude": 5.55,
                            "longitude": 5.55
                        },
                        "last_updated": "2026-04-08T07:25:15-07:00",
                        "last_deployed": "2026-04-08T14:25:15.123456+00:00"
                    }
                ],
                "type": "single",
                "manufacturer": "Testing",
                "last_updated": "2026-04-09T23:37:14.935411+00:00"
            },
            {
                "id": "6b5ac585-76fe-4af8-9813-f6f56a2c6cab",
                "display_id": "6b5ac585-76fe-4af8-9813-f6f56a2c6cab",
                "status": "deployed",
                "devices": [
                    {
                        "device_id": "fe5b4705-0b36-422c-846b-620d4aae98dd",
                        "mfr_device_id": "buoy002",
                        "label": "a",
                        "location": {
                            "latitude": 5.54,
                            "longitude": 5.54
                        },
                        "last_updated": "2026-04-08T07:25:15-07:00",
                        "last_deployed": "2026-04-08T14:25:15.123456+00:00"
                    },
                    {
                        "device_id": "fe5b4705-0b36-422c-846b-620d4aae98ee",
                        "mfr_device_id": "buoy003",
                        "label": "b",
                        "location": {
                            "latitude": 5.53,
                            "longitude": 5.53
                        },
                        "last_updated": "2026-04-08T07:25:15-07:00",
                        "last_deployed": "2026-04-08T14:25:15.123456+00:00"
                    }
                ],
                "type": "trawl",
                "manufacturer": "Testing",
                "last_updated": "2026-04-09T23:35:21.221668+00:00"
            }
        ]
    },
    "status": {
        "code": 200,
        "message": "OK"
    }
}
 
 

 

4. 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": "6b5ac585-76fe-4af8-9813-f6f56a2c6c32",
    "display_id": "6b5ac585-76fe-4af8-9813-f6f56a2c6c32",
    "status": "deployed",
    "devices": [
        {
            "device_id": "fe5b4705-0b36-422c-846b-620d4aae983b",
            "mfr_device_id": "buoy001",
            "label": "a",
            "location": {
                "latitude": 5.55,
                "longitude": 5.55
            },
            "last_updated": "2026-04-08T07:25:15-07:00",
            "last_deployed": "2026-04-08T14:25:15.123456+00:00"
        }
    ],
    "type": "single",
    "manufacturer": "Testing",
    "last_updated": "2026-04-09T23:37:14.935411+00:00"
}
 
 

 

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

Yes*

Unique identifier for the gear set.

 

Notes: 

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

mfr_set_id

 string (max 100)

Yes*

Manufacturer's string reference for the gear set. 

 

Notes: 

  • The request needs to include set_id or  mfr_set_id.
  • Defaults to set_id if not provided.

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. 

 

Notes: 

  • Not required for updates.

manufacturer_name

Existing identifier defined by EarthRanger.

Yes

Identifies the manufacturer. 

 

Notes: 

  • Will be provided by EarthRanger during the initial setup.

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.

 

Notes: 

  • 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.
  • Due to UI limitations, in trawls with two or more devices, only the serial number (mfr_device_id) of the first device is displayed in the Gear feed UI.

last_deployed

ISO 8601 datetime

Yes*

Timestamp when the device was last deployed. 

 

Notes: 

  • Required on gear deployments.
  • Always use the actual date and time the event happened.
  • Cannot be in the future.

last_updated

 ISO 8601 datetime

Yes 

Timestamp of the last update to this device. 

 

Notes: 

  • Required on gear hauls. 
  • Always use the actual date and time the event happened.
  • When reporting that a device has been hauled, the last_updated time you provide must be later than the time the device was originally deployed
     (last_deployed).
  • Cannot be in the future.

device_status

deployed, hauled, lost

Yes 

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

 

Notes: 

  • When hauling, it's important to use the same set_id and device_id as the request sent during 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
}
 
 

 

Redeploying gear in a new trawl set

A device can be redeployed to a new gear set after it has been hauled. However, the new deployment timestamp must be strictly later than the previous deployment.

  • If the new deployment time is after the previous one, the system will automatically mark the old gear set as hauled and record the new deployment.
  • If the new deployment time is the same as or earlier than the previous one, the system will reject the request. 

You will receive an error message that includes the ID of the conflicting gear set.

 

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"
    }
}
 
 

 

 

 

 

April 9, 2026