Skip to content

Koalasense public API documentation

This documentation describe how to use the public API of Koalasense.

This API is strictly restricted to the authorized persons.

Authorization

Authorization token

An authorization token has to be generated by Koalasense. This token is for your own use. You are not allowed to transmit it to a third-party.

How to use it

You will need to send an Authorization header with your token as Bearer token in each of your requests. Example:

GET https://{{host}}/api/public/v1/koala
Authorization: Bearer YOUR_TOKEN_HERE

Rate limit

Every token has a defined rate limit. This is done to ensure that no one can bring done the main database with too many requests. You will receive the status of your rate limit in the response header. Example:

X-Rate-Limit-koalaHistoryPerHour-limit: P1WT
X-Rate-Limit-koalaHistoryPerHour-usage-left: PT6DT10H
X-Rate-Limit-requestPerHour-limit: 10
X-Rate-Limit-requestPerHour-usage-left: 9

The durations use the ISO 8601 format.

Request per hour

This limit is self explainatory. This is the limit of request you can do per hour. If you overshoot this, you will have to wait the next hour before attempting again.

History per hour

This is specific to requesting the value history. This is the amount of history the token can request per hour. For instance: P30D means that the user can request for 30 days worth of koala history each hour. This limit is in total and not per koala. So if you have 10 koalas and a limit of P10D it means that, for example, you will be able either to retrive 10 days worth of history for 1 koala. Or, as another example, 1 day worth of history for 10 koalas. If this threshold is overshoot, you will have to wait another hour before requesting more.

API calls documentation

An OpenAPI documentation as well as a Swagger UI is at your disposal. If you wish to use the UI don't forget to enter your token.

Note on using the interval parameter

If you decide to use the interval parameter, values will be aggregated. The aggregation depends on the type of data. For example, temperature will be averaged, but rain will be summed. If you use an interval of 1 hour or 1 day, the query will be substantially faster due to materialized view being used.

Changelog

1.3.0 (2025-01-10)

  • Add solar radiation in W/m2 in values (solarRadiationWm2)

1.2.0 (2024-12-14)

  • Add RIMPro API
  • Remove id from koala history response
  • Add ability to request any interval
  • Add Leaf Wetness in gr/m2 in values (leafWetnessGrM2)
  • Leaf Wetness count deprecated in values (leafWetnessCount)
  • Add ability for token to have access to all devices
  • Koala number in string instead of integer
  • Add interval parameter in koala history

1.1.0 (2024-03-12)

  • Add ability for tokens to be linked to deviceId in Koalasense (transversal to multiple users)
  • Use Kustomize for deployment
  • add rainMm10m in values. This is the cumulated rain in mm for the last 10 minutes

1.0.2 (2024-02-09)

  • Add leafWetnessCount to the value history
  • id field in value deprecated

1.0.2 (2023-11-15)

  • Add token for security
  • Token are linked to a user in Koalasense
  • Implement rate limit
  • Request per hour
  • Amount of history per hour

1.0.1 (2023-05-14)

Initial release of the API. Includes Koala and value history retrieval.