EarthRanger Client

Introduction

EarthRanger is a software solution that helps protected area managers, ecologists, and wildlife biologists make informed operational decisions for wildlife conservation.

The earthranger-client (er-client) is a Python library for accessing the EarthRanger HTTP API. It simplifies interaction with the API by abstracting resource-based endpoints and offers both synchronous and asyncio clients, plus multi-threaded helpers for bulk reads.

Uses of er-client

• Extracting data for analysis
• Importing ecological or other historical data
• Integrating a new field sensor type. If you do and will be supporting multiple ER sites, contact us to talk about our Gundi integrations platform
• Performing external analysis that results in publishing an Alert on the ER platform.

Quick Start

See docs/examples/simple-example.py for a full sync example (pulse, subjects, tracks, create event, attach file, query events).

Installation

From PyPI:

pip install earthranger-client

Choosing sync vs async

Both clients take the same constructor arguments, apart from two async-only timeouts (see "Constructor arguments" below). The async client supports a subset of the sync client's endpoints (see "Async client scope" below).

Sync client (ERClient)

Import and construct with service_root and either username/password (+ client_id) or a bearer token:

from erclient import ERClient

# Username/password (client_id required)
client = ERClient(
    service_root="https://sandbox.pamdas.org",
    client_id="example_client_id",
    username="your_username",
    password="your_password",
    provider_key="your_provider_key",  # only needed for sensor / camera-trap posts
)
# Or with a bearer token
client = ERClient(service_root="https://sandbox.pamdas.org", token="your_bearer_token")

Common patterns:

import json
from datetime import datetime, timezone

# Single item
event = client.get_event(event_id="uuid")
subject = client.get_subject(subject_id="uuid")

# Paginated iteration (generators).
# `filter` must be a JSON-encoded string, not a dict.
event_filter = json.dumps({
    "date_range": {
        "lower": "2023-11-10T00:00:00-06:00",
        "upper": "2023-11-11T00:00:00-06:00",
    },
})
for event in client.get_events(filter=event_filter, max_results=100):
    ...
for obs in client.get_observations(
    start=datetime(2023, 11, 10, tzinfo=timezone.utc),
    end=datetime(2023, 11, 11, tzinfo=timezone.utc),
):
    ...

# Create / update
new_event = client.post_report({
    "event_type": "wildlife_sighting_rep",  # must match an event type in your ER site
    "title": "A new event",
    "location": {"latitude": 47.5978393, "longitude": -122.3308366},
})
client.post_sensor_observation(observation, sensor_type="generic")  # requires provider_key
client.post_event_file(event_id, filepath="/path/to/file", comment="...")

For bulk reads the sync client also provides get_objects_multithreaded(object="observations", ...).

Async client (AsyncERClient)

Use an async context manager so the HTTP session is always closed:

import asyncio
import json

from erclient import AsyncERClient

async def main():
    async with AsyncERClient(
        service_root="https://sandbox.pamdas.org",
        client_id="example_client_id",
        username="your_username",
        password="your_password",
        provider_key="your_provider_key",  # only needed for sensor / camera-trap posts
    ) as client:
        # Single-item calls: await
        event = await client.get_event(event_id="uuid")
        event_types = await client.get_event_types()

        # Stream events or observations: async for.
        # `filter` must be a JSON-encoded string, not a dict.
        event_filter = json.dumps({"date_range": {"lower": "2023-11-10T00:00:00-06:00"}})
        async for event in client.get_events(filter=event_filter, page_size=100):
            ...
        async for observation in client.get_observations(start="2023-11-10T00:00:00-06:00"):
            ...

        # Post (await)
        await client.post_sensor_observation(position)
        await client.post_report(report)
        await client.post_camera_trap_report(camera_trap_payload, file=file_handle)

asyncio.run(main())

Without a context manager, create the client and call await client.close() when finished:

async def main():
    client = AsyncERClient(service_root="...", client_id="...", username="...", password="...")
    try:
        await client.post_report(report)
        async for obs in client.get_observations(start="2023-11-10T00:00:00-06:00"):
            print(obs)
    finally:
        await client.close()

asyncio.run(main())

Async client scope

The async client currently supports:

• Post: Sensor observations (positions), events/reports, event attachments, camera trap reports, messages, event types, event categories; adding subjects to a subject group.
• Get: Events, single event, event types, event categories, observations, subject groups, subject sources, feature groups, sources (by manufacturer id), source assignments (subjectsources), user/me.
• Patch: Events, reports, subjects, event types, event categories.
• Delete: Events, event files, event notes, subjects, sources. Neither client can delete event types or event categories.
• Relationships: Adding/removing events to and from incidents; removing subjects from a subject group.

For the full sync surface (e.g. patrols, tracking data export, multithreaded bulk), use ERClient.

Constructor arguments

Both clients are declared as __init__(self, **kwargs), so every argument is keyword-only — ERClient("https://sandbox.pamdas.org") raises TypeError. Unrecognised keywords are silently ignored rather than rejected, so a typo such as provider_ke= leaves provider_key unset with no error.

Use either token, or client_id + username + password.

API versions

Event-type endpoints exist in two API versions. v1.0 is the default; pass version= to opt into v2.0:

from erclient import ERClient, VERSION_2_0

client = ERClient(service_root="https://sandbox.pamdas.org", token="your_bearer_token")
event_types = client.get_event_types(version=VERSION_2_0)

Four methods accept version=, on both clients — get_event_types, get_event_type, post_event_type, patch_event_type. Every other call is v1.0, and passing .../api/v2.0 as service_root does not change that (see "Constructor arguments").

Accepted values are VERSION_1_0 ("v1.0") and VERSION_2_0 ("v2.0"); the aliases "v1" and "v2" work too. Anything else raises ValueError, including "1.0" — the leading v is required.

patch_event_type identifies the event type differently per version, and raises ValueError when the key it needs is absent from the payload:

Caveat: the async client's patch_event_type reads event_type["value"] regardless of version (for logging), so on AsyncERClient a v1.0 payload must include value as well as id — a payload without value raises KeyError there, not ValueError.

Common method signatures (reference)

• Events:
  get_events(*, filter, page_size, max_results, ...) → sync: generator; async: async generator.
  get_event(*, event_id, include_details, include_notes, ...) → single dict.
  post_report(data) / post_event(data) → created resource.

• Observations:
  get_observations(*, subject_id, source_id, start, end, page_size, ...) → sync: generator; async: async generator.
  post_sensor_observation(observation, sensor_type='generic') → requires provider_key.

• Single resources:
  get_subject(subject_id), get_source_by_id(id), get_event_type(event_type_name, version=...), etc. return one object.

Sync vs async differences

Behaviors that are not shared, despite the common signatures above:

Best practices

• Async: Prefer async with AsyncERClient(...) as client: so the session is closed even on errors.
• Errors: Catch ERClientException; every client error subclasses it. Async maps common statuses to specific subclasses (ERClientBadRequest, ERClientBadCredentials, ERClientPermissionDenied, ERClientNotFound, ERClientRateLimitExceeded, ERClientInternalError, ERClientServiceUnreachable); unmapped statuses raise ERClientException itself, still with status_code set. Sync maps only 403 and 404 consistently, and sync-raised exceptions never populate exc.status_code (it is always None). For the codes sync does map, the exception type is the only signal — a 404 raises ERClientNotFound with no message at all — and the numeric status reaches the message text only for unmapped codes. There is no reliable way to branch on status with the sync client.
• Time ranges: Pass timezone-aware datetime for start/end — correct on both clients. Sync silently ignores ISO strings there; async accepts them. Filter date_range bounds are ISO 8601 strings with timezone, e.g. "2023-11-10T00:00:00-06:00".
• Sensor/camera-trap posts: Set provider_key on the client when posting sensor observations or camera trap reports.
• Large reads: Sync: consider get_objects_multithreaded for big list endpoints. Async: use page_size and optional batch_size in get_events/get_observations; cursor-based pagination is used by default.
• Rate limits: The API may throttle (e.g. one observation per second per source). Async maps 409/429 to ERClientRateLimitExceeded, with exc.retry_after in seconds; sync raises a plain ERClientException with exc.status_code unset — the status appears only in the message text.

For more on the EarthRanger API and event types, see EarthRanger and your ER instance's API documentation.