samsara-api 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

samsara/idling/client.py

@@ -0,0 +1,287 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.pagination import AsyncPager, SyncPager
+from ..core.request_options import RequestOptions
+from ..types.idling_event_object_response_body import IdlingEventObjectResponseBody
+from .raw_client import AsyncRawIdlingClient, RawIdlingClient
+from .types.idling_list_request_pto_state import IdlingListRequestPtoState
+
+
+class IdlingClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawIdlingClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawIdlingClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawIdlingClient
+        """
+        return self._raw_client
+
+    def list(
+        self,
+        *,
+        start_time: str,
+        end_time: str,
+        asset_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        operator_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        pto_state: typing.Optional[IdlingListRequestPtoState] = None,
+        min_air_temperature_millicelsius: typing.Optional[int] = None,
+        max_air_temperature_millicelsius: typing.Optional[int] = None,
+        exclude_events_with_unknown_air_temperature: typing.Optional[bool] = None,
+        min_duration_milliseconds: typing.Optional[int] = None,
+        max_duration_milliseconds: typing.Optional[int] = None,
+        tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        parent_tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        after: typing.Optional[str] = None,
+        limit: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[IdlingEventObjectResponseBody]:
+        """
+        Get idling events for the requested time duration.
+
+        **Note:** The data from this endpoint comes from the new Advanced Idling Report, which provides additional data fields for each idling event such as air temperature, geofence, PTO state and minimum idle time. This endpoint will initially include data from August 1, 2024. Approx. two weeks later, this will be further back dated to January 1, 2024. If you require additional historical data, you can access it via the [vehicle idling reports API](https://developers.samsara.com/reference/getvehicleidlingreports).
+
+         <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Idling** under the Fuel & Energy category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
+
+
+         **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.
+
+        Parameters
+        ----------
+        start_time : str
+            The start of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-11T19:00:00Z, 2015-09-12T14:00:00-04:00). Returns events that begin at or after this timestamp.
+
+        end_time : str
+            The end of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:00:00Z, 2015-09-15T14:00:00-04:00). Returns events that begin before this timestamp.
+
+        asset_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of asset IDs. Asset IDs only include vehicle IDs at this time.
+
+        operator_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of operator IDs. Operator IDs only include driver IDs at this time.
+
+        pto_state : typing.Optional[IdlingListRequestPtoState]
+            A filter on the data on this PTO (Power Take-Off) state. If no specific state is provided, data including any state will be included.  Valid values: `active`, `inactive`
+
+        min_air_temperature_millicelsius : typing.Optional[int]
+            A filter on the data based on the minimum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.
+
+        max_air_temperature_millicelsius : typing.Optional[int]
+            A filter on the data based on the maximum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.
+
+        exclude_events_with_unknown_air_temperature : typing.Optional[bool]
+            A filter on the data based on unknown air temperature value.
+
+        min_duration_milliseconds : typing.Optional[int]
+            A filter on the data based on the minimum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.
+
+        max_duration_milliseconds : typing.Optional[int]
+            A filter on the data based on the maximum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.
+
+        tag_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of tag IDs. Tag IDs only include vehicle IDs at this time.
+
+        parent_tag_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of parent tag IDs. Parent tag IDs only include vehicle IDs at this time.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        limit : typing.Optional[int]
+            The limit for how many objects will be in the response. Default and max for this value is 200 objects.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SyncPager[IdlingEventObjectResponseBody]
+            OK response.
+
+        Examples
+        --------
+        from samsara import Samsara
+
+        client = Samsara(
+            token="YOUR_TOKEN",
+        )
+        response = client.idling.list(
+            start_time="startTime",
+            end_time="endTime",
+        )
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
+        """
+        return self._raw_client.list(
+            start_time=start_time,
+            end_time=end_time,
+            asset_ids=asset_ids,
+            operator_ids=operator_ids,
+            pto_state=pto_state,
+            min_air_temperature_millicelsius=min_air_temperature_millicelsius,
+            max_air_temperature_millicelsius=max_air_temperature_millicelsius,
+            exclude_events_with_unknown_air_temperature=exclude_events_with_unknown_air_temperature,
+            min_duration_milliseconds=min_duration_milliseconds,
+            max_duration_milliseconds=max_duration_milliseconds,
+            tag_ids=tag_ids,
+            parent_tag_ids=parent_tag_ids,
+            after=after,
+            limit=limit,
+            request_options=request_options,
+        )
+
+
+class AsyncIdlingClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawIdlingClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> AsyncRawIdlingClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawIdlingClient
+        """
+        return self._raw_client
+
+    async def list(
+        self,
+        *,
+        start_time: str,
+        end_time: str,
+        asset_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        operator_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        pto_state: typing.Optional[IdlingListRequestPtoState] = None,
+        min_air_temperature_millicelsius: typing.Optional[int] = None,
+        max_air_temperature_millicelsius: typing.Optional[int] = None,
+        exclude_events_with_unknown_air_temperature: typing.Optional[bool] = None,
+        min_duration_milliseconds: typing.Optional[int] = None,
+        max_duration_milliseconds: typing.Optional[int] = None,
+        tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        parent_tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        after: typing.Optional[str] = None,
+        limit: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[IdlingEventObjectResponseBody]:
+        """
+        Get idling events for the requested time duration.
+
+        **Note:** The data from this endpoint comes from the new Advanced Idling Report, which provides additional data fields for each idling event such as air temperature, geofence, PTO state and minimum idle time. This endpoint will initially include data from August 1, 2024. Approx. two weeks later, this will be further back dated to January 1, 2024. If you require additional historical data, you can access it via the [vehicle idling reports API](https://developers.samsara.com/reference/getvehicleidlingreports).
+
+         <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Idling** under the Fuel & Energy category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
+
+
+         **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.
+
+        Parameters
+        ----------
+        start_time : str
+            The start of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-11T19:00:00Z, 2015-09-12T14:00:00-04:00). Returns events that begin at or after this timestamp.
+
+        end_time : str
+            The end of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:00:00Z, 2015-09-15T14:00:00-04:00). Returns events that begin before this timestamp.
+
+        asset_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of asset IDs. Asset IDs only include vehicle IDs at this time.
+
+        operator_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of operator IDs. Operator IDs only include driver IDs at this time.
+
+        pto_state : typing.Optional[IdlingListRequestPtoState]
+            A filter on the data on this PTO (Power Take-Off) state. If no specific state is provided, data including any state will be included.  Valid values: `active`, `inactive`
+
+        min_air_temperature_millicelsius : typing.Optional[int]
+            A filter on the data based on the minimum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.
+
+        max_air_temperature_millicelsius : typing.Optional[int]
+            A filter on the data based on the maximum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.
+
+        exclude_events_with_unknown_air_temperature : typing.Optional[bool]
+            A filter on the data based on unknown air temperature value.
+
+        min_duration_milliseconds : typing.Optional[int]
+            A filter on the data based on the minimum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.
+
+        max_duration_milliseconds : typing.Optional[int]
+            A filter on the data based on the maximum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.
+
+        tag_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of tag IDs. Tag IDs only include vehicle IDs at this time.
+
+        parent_tag_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+            A filter on the data based on this comma-separated list of parent tag IDs. Parent tag IDs only include vehicle IDs at this time.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        limit : typing.Optional[int]
+            The limit for how many objects will be in the response. Default and max for this value is 200 objects.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncPager[IdlingEventObjectResponseBody]
+            OK response.
+
+        Examples
+        --------
+        import asyncio
+
+        from samsara import AsyncSamsara
+
+        client = AsyncSamsara(
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            response = await client.idling.list(
+                start_time="startTime",
+                end_time="endTime",
+            )
+            async for item in response:
+                yield item
+
+            # alternatively, you can paginate page-by-page
+            async for page in response.iter_pages():
+                yield page
+
+
+        asyncio.run(main())
+        """
+        return await self._raw_client.list(
+            start_time=start_time,
+            end_time=end_time,
+            asset_ids=asset_ids,
+            operator_ids=operator_ids,
+            pto_state=pto_state,
+            min_air_temperature_millicelsius=min_air_temperature_millicelsius,
+            max_air_temperature_millicelsius=max_air_temperature_millicelsius,
+            exclude_events_with_unknown_air_temperature=exclude_events_with_unknown_air_temperature,
+            min_duration_milliseconds=min_duration_milliseconds,
+            max_duration_milliseconds=max_duration_milliseconds,
+            tag_ids=tag_ids,
+            parent_tag_ids=parent_tag_ids,
+            after=after,
+            limit=limit,
+            request_options=request_options,
+        )