Chapter 11 API Reference

Base URL: https://api.internetofwildlife.com
Protocol: HTTPS
Method: All endpoints use POST
Encoding: JSON
Timeout: 60 seconds per request

All endpoints require an API token passed in the JSON request body as token. The token is loaded from a .env file via dotenv and accessed with Sys.getenv("MY_TOKEN").

library(dotenv)
load_dot_env()
my_token <- Sys.getenv("MY_TOKEN")

11.1 Typical Workflow

1. Authenticate       load_dot_env() -> Sys.getenv("MY_TOKEN")
2. List projects      POST /station/api/projects
3. List stations      POST /station/api/stations/         (per project)
4. List files         POST /station/api/file-list          (per station, paginated)
5. Download files     POST /station/api/download-file/     (per file)
6. (Optional) Import  file_handle() -> db_prep() -> db_insert()

The get_my_data() function orchestrates this entire workflow in a single call.

11.2 POST Wrapper

All endpoints (except direct calls in get_my_projects and project_list) go through the post() function in R/post.R:

post(endpoint, payload = NULL, show_progress = FALSE)

Automatically injects token = my_token into every request
60-second timeout on all requests
Detects HTTP 503 and emits a warning suggesting narrower date ranges or pagination
Calls httr::stop_for_status() to raise on other HTTP errors
Optional progress bar via httr::progress()

11.3 List Projects Projects

POST /station/api/projects

Retrieves all projects associated with the authenticated user’s account.

11.3.1 Parameters

Field	Type	Required	Description
`token`	string	REQUIRED	API authentication token

11.3.2 curl Example

curl -X POST https://api.internetofwildlife.com/station/api/projects \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN"}'

11.3.3 Response

200 OK

{
  "projects": [
    {
      "id": "abc123",
      "name": "My Wildlife Project"
    },
    {
      "id": "def456",
      "name": "Raptor Tracking Study"
    }
  ]
}

11.3.4 Errors

Status	Cause	What You See
401	Invalid or expired API token	`httr::stop_for_status()` raises: `“Unauthorized (HTTP 401)”`
503	Server overloaded or temporarily down	Warning: `“Server query timeout — try narrowing your date range or using pagination”`, then execution stops
Timeout	Network issue or server unreachable	R error: `“Timeout was reached”` after 60 seconds
Empty token	`.env` file missing or `MY_TOKEN` not set	API returns auth error; `Sys.getenv(“MY_TOKEN”)` silently returns `““` if unset
Not found	Specified `myproject` name doesn’t match any project	`“The project you entered is not found in your project list. Check your spelling and if you have access to the project.”`

11.3.5 R Package Functions

get_my_projects() in R/get_my_projects.R — returns a character vector of project names
project_list() in R/project_list.R — returns filtered project list with optional name matching

11.4 List Stations Stations

POST /station/api/stations/

Retrieves all sensor stations deployed under a given project.

11.4.1 Parameters

Field	Type	Required	Description
`token`	string	REQUIRED	API authentication token
`project-id`	string	REQUIRED	Project identifier obtained from the List Projects endpoint

11.4.2 curl Example

curl -X POST https://api.internetofwildlife.com/station/api/stations/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "project-id": "YOUR_PROJECT_ID"}'

11.4.3 Response

200 OK

{
  "stations": [
    {
      "station": {
        "id": "STATION-001"
      },
      "deploy-at": "2024-01-15T00:00:00.000Z",
      "end-at": "2024-06-01T00:00:00.000Z"
    },
    {
      "station": {
        "id": "STATION-002"
      },
      "deploy-at": "2024-03-01T00:00:00.000Z",
      "end-at": null
    }
  ]
}

Each station entry includes:

station.id — unique station identifier
deploy-at — ISO 8601 deployment start timestamp
end-at — ISO 8601 deployment end timestamp (null for active stations)

11.4.4 Errors

Status	Cause	What You See
401	Invalid or expired API token	`httr::stop_for_status()` raises: `“Unauthorized (HTTP 401)”`
404	`project-id` does not exist or user lacks access	`httr::stop_for_status()` stops execution with an HTTP error
503	Server overloaded or temporarily down	Warning: `“Server query timeout — try narrowing your date range or using pagination”`, then execution stops
Timeout	Network issue or server unreachable	R error: `“Timeout was reached”` after 60 seconds
Empty list	Project exists but has no deployed stations	Response returns `“stations”: []`; downstream code in `get_data()` skips processing

11.4.5 R Package Functions

get_stations() in R/get_stations.R
get_data() in R/get_data.R — iterates stations to build file lists

11.5 List Station Files Files

POST /station/api/file-list

Retrieves metadata for data files available from a specific station, with optional date range and file type filtering. Supports pagination via limit and offset.

11.5.1 Parameters

Field	Type	Required	Description
`token`	string	REQUIRED	API authentication token
`station-id`	string	REQUIRED	Station identifier obtained from the List Stations endpoint
`begin`	date	REQUIRED	Start date for file search (ISO date format, e.g. `2024-01-01`)
`end`	date	optional	End date for file search. Defaults to today if omitted.
`file-types`	string[]	optional	Filter by file types: `data`, `node-data`, `gps`, `log`, `telemetry`, `sensorgnome`, `ble`, `blu`
`limit`	integer	optional	Maximum number of files to return (for pagination)
`offset`	integer	optional	Number of files to skip (for pagination)

11.5.2 curl Examples

Basic request (required fields only):

curl -X POST https://api.internetofwildlife.com/station/api/file-list \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "station-id": "YOUR_STATION_ID", "begin": "2024-01-01"}'

Full request with all options:

curl -X POST https://api.internetofwildlife.com/station/api/file-list \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "station-id": "YOUR_STATION_ID",
    "begin": "2024-01-01",
    "end": "2024-02-01",
    "file-types": ["data", "gps"],
    "limit": 100,
    "offset": 0
  }'

11.5.3 Response

200 OK

{
  "files": [
    {
      "id": "file-789",
      "name": "CTT-STATION001-data.csv.gz"
    },
    {
      "id": "file-790",
      "name": "CTT-STATION001-gps.csv.gz"
    }
  ]
}

Note: Large date ranges may cause 503 server timeouts. Use get_station_file_list_paginated() to handle this automatically. The paginated version retries failed chunks up to max_retries times (default 3) with exponential backoff (2s, 4s, 6s).

11.5.4 Errors

Status	Cause	What You See
401	Invalid or expired API token	`httr::stop_for_status()` raises: `“Unauthorized (HTTP 401)”`
503	Date range too large; server times out	Warning: `“Server query timeout — try narrowing your date range or using pagination”`. The paginated wrapper catches this and retries: `“Request timed out, retrying (attempt X of Y)…”`
Timeout	Network issue or server unreachable	R error: `“Timeout was reached”` after 60 seconds. Paginated wrapper retries up to `max_retries` times with exponential backoff.
Invalid type	A value in `file-types` is not one of the 8 valid types	Warning: `“WARNING: invalid file type specified - ignoring: <type>”`. Invalid types are dropped; request proceeds with valid types only.
404	`station-id` does not exist	`httr::stop_for_status()` stops execution with an HTTP error
Empty result	Station has no files for the given date range	`get_data()` prints `“no files found from API”` and returns an empty list
Max retries	Paginated wrapper exhausts all retry attempts on a chunk	The original error is re-thrown via `stop(e)`, halting execution

11.5.5 R Package Functions

get_station_file_list() in R/get_station_file_list.R — single request with optional pagination params
get_station_file_list_paginated() in R/get_station_file_list_paginated.R — automatic date-chunked pagination with retry logic

11.6 Download File Files

POST /station/api/download-file/

Downloads the contents of a single data file by its ID.

11.6.1 Parameters

Field	Type	Required	Description
`token`	string	REQUIRED	API authentication token
`file-id`	string	REQUIRED	File identifier obtained from the List Station Files endpoint
`bypass-encoding`	string	optional	Set to `“plain”` to bypass encoding. Used automatically as a fallback on retry.

11.6.2 curl Examples

Basic download:

curl -X POST https://api.internetofwildlife.com/station/api/download-file/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "file-id": "YOUR_FILE_ID"}'

With bypass encoding (fallback on error):

curl -X POST https://api.internetofwildlife.com/station/api/download-file/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "file-id": "YOUR_FILE_ID", "bypass-encoding": "plain"}'

11.6.3 Response

200 OK — Raw file content (CSV text, UTF-8 encoded)

TagId,NodeId,TagRSSI,Validated,Time
TAG-001,NODE-A,-70,1,2024-01-15 12:00:00
TAG-001,NODE-B,-85,1,2024-01-15 12:00:00

In batch downloads via get_data(), each file result is tracked in a dataframe. The final summary prints: "Download complete: X succeeded, Y failed out of Z files"

11.6.4 Errors

Status	Cause	What You See
401	Invalid or expired API token	`httr::stop_for_status()` raises: `“Unauthorized (HTTP 401)”`
404	`file-id` does not match any file on the server	`httr::stop_for_status()` stops execution with an HTTP error
500	File content has encoding issues the server can’t handle	`download_files()` prints `“Here’s the original error message:”` followed by the error detail, then automatically retries with `bypass-encoding = “plain”`
500 (retry)	File is corrupted or unrecoverable (retry also fails)	Error propagates up; `get_data()` catches it per-file and records `status = “failed”` in results dataframe
503	Server overloaded or temporarily down	Warning: `“Server query timeout — try narrowing your date range or using pagination”`, then execution stops
Timeout	Network issue or server unreachable	R error: `“Timeout was reached”` after 60 seconds
Batch failure	Any error during a single file download within `get_data()`	File is marked `“failed”` in the results dataframe; remaining files continue. Final summary: `“Download complete: X succeeded, Y failed out of Z files”`

11.6.5 R Package Functions

download_files() in R/download_files.R
Called from get_data() in R/get_data.R for each file in the download queue