Integrate with ER Buoy and RMWHub

Overview

EarthRanger Buoy integration documentation is also found in swagger format here: https://buoy.dev.pamdas.org/api/v1.0/docs/interactive/#/Buoy for our test environment

This service exposes REST endpoints under the path prefix “/api/v1.0/” with resources for managing and querying gear objects. 

Note: The swagger documentation is the primary source. The swagger documentation is always up to date with the API. This documentation is maintained separately. 

API Introduction

Base URL

Endpoints

  • GET /api/v1.0/gear/: Returns a paginated list of trawls and devices that match the query parameters.
  • GET /api/v1.0/gear/{id}: Returns a single trawl by its identifier (path parameter id is required).
  • POST /api/v1.0/gear/: Creates a new trawl or updates trawl data.

Headers

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

Get Gear by Location

Returns Gear within 5nm 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 (number): Include subjects within a range of 5 nautical miles from this latitude; latitude must be between -90 and 90.                
  • lon (number): Include subjects within a range of 5 nautical miles from this longitude; longitude must be between -180 and 180.                
  • updated_since (date): Return items updated since the given timestamp.                
  • state (string): Filter by state. Use “deployed” for in-water gear or “hauled” for recovered gear.                

Code Examples

cURL

Basic request:

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 (e.g., https://buoy.pamdas.org, or https://buoy.dev.pamdas.org) 

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

 
 

Response Example

{
  "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": "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"
      }
    ]
  },
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Get Gear by ID

Returns a single trawl with a matching ID

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 (number): Include subjects within a range of 5 nautical miles from this latitude; latitude must be between -90 and 90.                
  • lon (number): Include subjects within a range of 5 nautical miles from this longitude; longitude must be between -180 and 180.                
  • updated_since (date): Return items updated since the given timestamp.                
  • state (string): Filter by state. Use “deployed” for in-water gear or “hauled” for recovered gear.                   

Code Examples

cURL

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 (e.g., https://buoy.pamdas.org, or https://buoy.dev.pamdas.org) 

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

 
 

Response Example

{
  "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/

Trawl Field Information 

Field

Type

Required?

Notes

set_id

string (UUID)

No

Will be generated automatically if omitted.

Global - Across manufacturers

Returned in the response

vessel_id

string

No

Max Length: 255

mfr_set_id

string

No

Manufacturer specific set_id. This is different from set_id, which is global. 

Intended for use by manufacturers.

Can be null, not automatically generated. 

owner_id

string

No

  

set_display_id

string

No

Can be used by the user interface for visibility on the mobile apps and web apps. Often matches device serial number. 

permit_number

string

No

Optional; for regulatory/compliance tracking

Max Length: 255

deployment_type

string

Yes

trawl | single | surface  

devices_in_set

integer

No

Number of devices in this deployment.

last_updated

string (ISO 8601 UTC)

No

Date of most recent update of gear/trawl data. 

Initial_deployment_date

string (ISO 8601 UTC)

Yes

Date trawl was initially deployed. 

manufacturer_name

string

Yes

Will be provided by EarthRanger

devices

array

No

An array of devices that is part of the set. Can be single or multiple. 

set_additional_data

object

No

Any additional information the manufacturer would like to store with the set.

 

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

 

Device Field Information

Property

Type

Required?

Notes

device_id

string (UUID)

Yes

Global Unique identifier

mfr_device_id

string

Yes

Unique to the manufacturer 

mfr_id

string

No

ID of the manufacturer. Usually matches the manufacturer_name of the set. 

Ex: “Ropeless Systems”, “Teledyne” 

last_deployed

string (ISO 8601)

Yes

Date and time of deployment

last_updated

string (ISO 8601)

Yes

Date of the most recent data update. 

device_status

string

Yes

deployed | hauled | lost   

positioning_type

string

No

Usually “gps”.

gps |  gps_manual |  acoustic | rfid

release_type

string

No

timed | acoustic | galvanic

location

object

No

 {
 "lat": 0,
 "long": 0
}

positioning_type

string

No

gps | acoustic  

device_additional_data

object

No

Any additional information the manufacturer would like to store with the device.

 

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

device_display_id

string

No

For display on the user interfaces. 

device_pgn_data

object

No

 {
 "custom_field1": "value1",
 "custom_field2": 42
}

Code Examples

cURL

Example 1:

curl --location 'https://{{site}}/api/v1.0/gear' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your token>' \
--data '{
  "deployment_type": "trawl",
  "manufacturer_name": "RMWHub",
  "set_id": "cf94d09d-b2b5-43cf-be2b-40f8d663b22f",
  "devices_in_set": 2,
  "devices": [
    {
      "device_id": "860326d9-71c6-47b5-b649-5310801598d3",
      "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
      },
      "device_additional_data": "{\"id\":\"860326d9-71c6-47b5-b649-5310801598d3\",\"sequence\":1,\"latitude\":32.7452697,\"longitude\":-117.2490677,\"manufacturer\":null,\"serial_number\":null,\"deploy_datetime_utc\":\"2025-12-30T17:34:19\",\"surface_datetime_utc\":null,\"retrieved_datetime_utc\":null,\"status\":\"deployed\",\"accuracy\":\"gps\",\"release_type\":\"acoustic\",\"is_on_end\":true}",
      "release_type": "acoustic"
    },
    {
      "device_id": "5821f28e-d86a-4dfd-be2e-9d8122ac2898",
      "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
      },
      "device_additional_data": "{\"id\":\"5821f28e-d86a-4dfd-be2e-9d8122ac2898\",\"sequence\":2,\"latitude\":32.7452823,\"longitude\":-117.2491004,\"manufacturer\":null,\"serial_number\":null,\"deploy_datetime_utc\":\"2025-12-30T17:34:27\",\"surface_datetime_utc\":null,\"retrieved_datetime_utc\":null,\"status\":\"deployed\",\"accuracy\":\"gps\",\"release_type\":\"acoustic\",\"is_on_end\":true}",
      "release_type": "acoustic"
    }
  ],
  "initial_deployment_date": "2025-12-30T21:34:19+00:00"
}
'

Example 2:

curl --location 'https://buoy.staging.pamdas.org/api/v1.0/gear' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer fb2f4d0776e367fa14a37cddf4653e89dbefdeb1' \
--data '{
  "deployment_type": "single",
  "manufacturer_name": "RMWHub",
  "set_id": "42780724-98f8-459b-8aaa-572cda8c3547",
  "devices_in_set": 1,
  "devices": [
    {
      "device_id": "42780724-98f8-459b-8aaa-572cda8c3547",
      "last_deployed": "2025-12-30T19:40:55+00:00",
      "last_updated": "2025-12-30T19:40:55+00:00",
      "device_status": "deployed",
      "location": {
        "latitude": 20.622157, 
        "longitude": -103.471536
      },
      "device_additional_data": "{\"id\":\"42780724-98f8-459b-8aaa-572cda8c3547\",\"sequence\":1,\"latitude\":19.48999505,\"longitude\":-99.10672661,\"manufacturer\":null,\"serial_number\":null,\"deploy_datetime_utc\":\"2025-12-30T19:40:55\",\"surface_datetime_utc\":null,\"retrieved_datetime_utc\":null,\"status\":\"deployed\",\"accuracy\":\"gps\",\"release_type\":\"acoustic\",\"is_on_end\":true}",
      "release_type": "acoustic"
    }
  ],
  "initial_deployment_date": "2025-12-30T19:40:55+00:00"
}
'

{{site}}: Use the site you have been granted access to (e.g., https://buoy.pamdas.org, or https://buoy.dev.pamdas.org) 

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

 
 

Response Example

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