Time Series Data API

General

The Koherent Time Series Data API is used for retrieving historical measurement data, via a HTTP REST API.

API Base URL

The base URL for all API calls is

https://api.koherent.io

Firewalls

If using corporate firewalls or similar software, it might be necessary to whitelist the above base URL and the URL used for downloading measurement data:

https://koherent-reservoir-analytics-prod.s3.eu-north-1.amazonaws.com

Authentication

Auth is required for all API endpoints and is done by sending the provided API key in the Authorization header in the format

"Authorization": "Bearer your-api-key"

Koherent Management & Data API keys are long strings beginning with the identifier kma_. The keys are user and use-case specific and should be considered confidential. If you suspect that your API key has been compromised, please contact Koherent to have it reset.

Endpoints

Measurement data

Used for retrieving historical measurement data for a specific Grid.

Due to technical constraints, there may be a delay of up to 24 hours between measurement and the data being available to query via this API.

Get measurements in time range

GET /grids/:gridUid/data/measurements

Fetch measurements in a time range at a specific granularity. Depending on the Grid configuration, the data may be either of position or distance type.

Query limits: Currently, the time range between query start and end date is limited to a maximum of 25 hours. The maximum number of query requests is also limited per day.

Path parameters

Name	Type	Data type	Description
gridUid	required	string	The UID of the Grid to query data for

Query parameters

Name	Type	Data type	Description
startTimeMs	required*	int32	Time range start value (Unix time in milliseconds, e.g. 1724773826000)
endTimeMs	required*	int32	Time range end value (Unix time in milliseconds)
startTimeISO	required*	string	Time range start value (ISO 8601 UTC date-time string, e.g. 2024-08-27T15:50:26.000Z)
endTimeISO	required*	string	Time range end value (ISO 8601 UTC date-time string)
granularityMs	optional	int32	Aggregate data to desired time interval between data points (milliseconds). Defaults to no aggregation
columns	optional	string	The data columns to include. Separate multiple values with commas. The available columns are listed in the data types section. Defaults to all.
targets	optional	string	The IDs of the targets to retrieve data for. Separate multiple values with commas. Defaults to all
dataType	optional	string	The type of data to retrieve. Either position or distance. Defaults to position.

*) Time range endpoints must always be provided. I.e. either startTimeMs and endTimeMs OR startTimeISO and endTimeISO must be included in all requests.

Responses

HTTP status	Status	content-type	Response
200	Success	text/csv	A CSV formatted table of either position or distance data
400	Invalid request	application/json	Error
404	Grid not found	application/json	Error
429	Too many requests	application/json	Error

Data Types

Position Data (CSV)

Column	Data type	Description
target_id	string	The ID of the target
timestamp	string	The time of the measurement in UTC (ISO 8601 date-time string)
x	float64	Target x coordinate
y	float64	Target y coordinate
z	float64	Target z coordinate
yaw	float64	Target yaw angle in degrees
pitch	float64	Target pitch angle in degrees
roll	float64	Target roll angle in degrees
error_x	float64	Target x coordinate error estimate
error_y	float64	Target y coordinate error estimate
error_z	float64	Target z coordinate error estimate
error_yaw	float64	Target yaw angle error estimate in degrees
error_pitch	float64	Target pitch angle error estimate in degrees
error_roll	float64	Target roll angle error estimate in degrees

Example

"timestamp","x","y"
"2024-09-27T13:04:57.850255286Z","61.448910842784292","-0.1233040417274127"
"2024-09-27T13:04:57.950255286Z","61.448901621545484","-0.12332864493494869"

Distance Data (CSV)

Field	Type	Data type	Description
target_id	string	The ID of the target
timestamp	required	string	The time of the measurement (ISO 8601 timestamp)
d	required	float64	The distance in meters
error_d	required	float64	The distance error estimate in meters

Example

"timestamp","d"
"2025-01-14T22:56:01.5782653Z","84.298151721545321"

Error

Field	Data type	Description
status	int	A HTTP status code
message	string	A human-readable error description

Example

{
    "status": 400, "message": "Bad request: Requested non-existent column 'foo'"
}

Examples

Shell

Using cURL.

Fetch measurement data and write it to the file data.csv:

curl --location 'https://api.koherent.io/grids/some-grid-uid/data/measurements' \
--url-query 'startTimeISO=2024-10-01T00:00:00Z' \
--url-query 'endTimeISO=2024-10-02T00:00:00Z' \
--url-query 'columns=timestamp,target_id,x,y,z' \
--url-query 'granularityMs=1000' \
--fail \
--header 'Authorization: Bearer <your-api-key>' \
> data.csv

Python

The examples use the Requests client, which can be installed using:

pip3 install requests~=2.32.3

note

A Python version >= 3.8 is required.

Fetch measurement data:

import requests

api_key = "your-api-key"
grid_uid = "some-grid-uid-123"

url = f"https://api.koherent.io/grids/{grid_uid}/data/measurements"
headers = { "Authorization": f"Bearer {api_key}" }
params = {
    "startTimeMs": 1727740800000,
    "endTimeMs": 1727740830000,
    "columns": "timestamp,x,y,z",
}

response = requests.request("GET", url, headers=headers, params=params)

response.raise_for_status() # Throw an error if the API request was unsuccessful

print(response.text)