pyroclient.client#

The client subpackage contains the core definition of the API client.

API Client#

class pyroclient.client.Client(token: str, host: str = 'https://api.pyronear.org', timeout: int = 10, **kwargs)[source]#

Isometric Python client for Pyronear wildfire detection API

Parameters
  • token – your personal API token

  • endpoint – the host for your instance of pyronear API

  • timeout (int) – number of seconds before request timeout

  • kwargs – optional parameters of requests.post

create_detection(media: bytes, bboxes: List[Tuple[float, float, float, float, float]], pose_id: int, crops: Optional[List[bytes]] = None, recorded_at: Optional[str] = None, temporal_model_scores: Optional[List[float]] = None) → Response[source]#

Notify the detection of a wildfire on the picture taken by a camera.

>>> from pyroclient import Client
>>> api_client = Client("MY_CAM_TOKEN")
>>> with open("path/to/my/file.ext", "rb") as f: data = f.read()
>>> response = api_client.create_detection(data, bboxes=[(.1,.1,.5,.8,.5)], pose_id=12)
Parameters
  • media – byte data of the picture

  • bboxes – list of tuples where each tuple is a relative coordinate in order xmin, ymin, xmax, ymax, conf. An empty list reports a frame with no detection: the API attaches it to recently seen sequences of the pose (keeping their frame timeline continuous) and stores nothing otherwise (204).

  • pose_id – pose_id of the detection

  • crops – optional list of cropped pictures, one per bbox (must align with bboxes). Each crop frames a single object, so its length must equal that of bboxes.

  • recorded_at – optional ISO 8601 timestamp of when the image was captured on-device. Timezone-aware values are converted to UTC server-side; defaults to server now if omitted.

  • temporal_model_scores – optional smoke probabilities (0 to 1) from the temporal model run on the device, one per bbox (must align with bboxes). When given, the API applies its own threshold to them instead of scoring the sequences itself.

Returns

HTTP response

create_occlusion_mask(pose_id: int, mask: str) → Response[source]#

Create a create occlusion_mask for a pose

>>> api_client.create_occlusion_mask(pose_id=1, mask="(0.1,0.1,0.9,0.9)")
create_pose(camera_id: int, azimuth: float, patrol_id: Optional[int] = None, active: bool = True) → Response[source]#

Create a pose for a camera

>>> api_client.create_pose(camera_id=1, azimuth=120.5, patrol_id=3)
delete_occlusion_mask(mask_id: int) → Response[source]#

Delete an occlusion mask

>>> api_client.delete_occlusion_mask(mask_id=1)
delete_pose(pose_id: int) → Response[source]#

Delete a pose

>>> api_client.delete_pose(pose_id=1)
fetch_cameras() → Response[source]#

List the cameras accessible to the authenticated user. By default, only trustable cameras are returned.

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_cameras()
Returns

HTTP response

fetch_detections(limit: int = 100, offset: int = 0) → Response[source]#

List a page of detections accessible to the authenticated user.

Pages default to 100 rows (maximum 500), ordered by ID. Advance offset to fetch more.

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_detections()
Returns

HTTP response

fetch_latest_sequences() → Response[source]#

List the latest sequences accessible to the authenticated user

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_latest_sequences()
Returns

HTTP response

fetch_organizations() → Response[source]#

List the organizations accessible to the authenticated user

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_organizations()
Returns

HTTP response

fetch_sequences_detections(sequence_id: int, limit: Optional[int] = None, desc: bool = True, with_crop: bool = True, sampling: int = 1, offset: int = 0) → Response[source]#

List the detections of a sequence

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_sequences_detections(1)
Parameters
  • sequence_id – ID of the associated sequence entry

  • limit – maximum number of detections to fetch. Unset (the default) lets the API pick: 10, or the size of the whole sampled span capped at 500 when sampling is set

  • desc – whether to order the detections by created_at in descending order

  • with_crop – whether to include the crop_url for detections that have a crop

  • sampling – keep one detection every N (1 = all, max 10000). The kept frames do not depend on desc. Leave limit unset to span the sequence, and read the X-Sampled-Total / X-Sampled-Truncated response headers

  • offset – raw detections to skip, from the oldest end when sampling. Page by advancing it in multiples of sampling

Returns

HTTP response

fetch_sequences_from_date(from_date: str, limit: int = 15, offset: int = 0) → Response[source]#

List the sequences accessible to the authenticated user for a specific date

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.fetch_sequences_from_date("2023-07-04")
Parameters
  • from_date – date of the sequences to fetch

  • limit – maximum number of sequences to fetch

  • offset – number of sequences to skip before starting to fetch

Returns

HTTP response

get_current_poses(camera_id: Optional[int] = None) → Response[source]#

Fetch poses for the authenticated camera.

For admin/agent tokens, provide camera_id to retrieve poses via the camera endpoint.

get_detection_url(detection_id: int) → Response[source]#

Retrieve the URL of the media linked to a detection

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.get_detection_url(1)
Parameters

detection_id – ID of the associated detection entry

Returns

HTTP response

get_occlusion_mask(mask_id: int) → Response[source]#

get mask from occlusion mask

>>> api_client.get_occlusion_mask(mask_id=1")
heartbeat(timeout: Optional[int] = None) → Response[source]#

Update the last ping of the camera

>>> from pyroclient import Client
>>> api_client = Client("MY_CAM_TOKEN")
>>> response = api_client.heartbeat()
Parameters

timeout – request timeout in seconds for this call only; defaults to the client timeout

Returns

HTTP response containing the update device info

label_sequence(sequence_id: int, is_wildfire: str) → Response[source]#

Update the label of a sequence made by a camera

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.label_sequence(1, is_wildfire="wildfire_smoke")
Parameters
  • sequence_id – ID of the associated sequence entry

  • is_wildfire – whether this sequence is confirmed as a wildfire

Returns

HTTP response

list_pose_masks(pose_id: int) → Response[source]#

List occlusion masks for a pose (given its pose_id)

>>> api_client.list_pose_masks(pose_id=1)
patch_occlusion_mask(mask_id: int, mask: str) → Response[source]#

Update an occlusion mask

>>> api_client.patch_occlusion_mask(mask_id=1, mask="(0.1,0.2,0.9,0.3)")
patch_pose(pose_id: int, azimuth: Optional[float] = None, patrol_id: Optional[int] = None, active: Optional[bool] = None) → Response#

Update a pose

>>> api_client.update_pose(pose_id=1, azimuth=90.0)
unmatch_alert_sequence(alert_id: int, sequence_id: int) → Response[source]#

Detach a sequence from an alert. If the sequence is no longer linked to any alert, a new alert is created for it.

>>> from pyroclient import client
>>> api_client = Client("MY_USER_TOKEN")
>>> response = api_client.unmatch_alert_sequence(1, 2)
Parameters
  • alert_id – ID of the alert the sequence should be detached from

  • sequence_id – ID of the sequence to detach

Returns

HTTP response

update_last_image(media: bytes) → Response[source]#

Update the last image of the camera

>>> from pyroclient import Client
>>> api_client = Client("MY_CAM_TOKEN")
>>> with open("path/to/my/file.ext", "rb") as f: data = f.read()
>>> response = api_client.update_last_image(data)
Returns

HTTP response containing the update device info

update_pose(pose_id: int, azimuth: Optional[float] = None, patrol_id: Optional[int] = None, active: Optional[bool] = None) → Response[source]#

Update a pose

>>> api_client.update_pose(pose_id=1, azimuth=90.0)
update_pose_image(pose_id: int, media: bytes) → Response[source]#

Update the image of a pose

>>> from pyroclient import Client
>>> api_client = Client("MY_TOKEN")
>>> with open("path/to/my/file.ext", "rb") as f: data = f.read()
>>> response = api_client.update_pose_image(pose_id=1, media=data)
Parameters
  • pose_id – ID of the pose

  • media – byte data of the image

Returns

HTTP response containing the updated pose info