Kayrros Platform APIs API Reference

This is the documentation of Kayrros Platform REST APIs. You can access the general Platform documentation here

Kayrros Platform REST APIs can be used to programmatically retrieve datasets and their metadata.

On the right side of this section you will find the server URL that should be used when calling the REST APIs below.

You must authenticate your requests as explained in the Authentication section below

API Endpoint
https://platform.api.kayrros.com/
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https

Authentication

Bearer Token

Kayrros specific security

Please note that Kayrros security handler is not oauth2 standard

Every call made to the API must provide an Authorization header specifying an access token with the form Bearer {your_token} as explained below.

How to get Authorization token

1 - Login Request

  1. Create HTTPS POST request to https://auth.kayrros.com/v3/login

    request.body

     {
   "email": "USER_EMAIL",
   "password": "USER_PASSWORD"
 }

  2. Get your access token

    response.body

     {
   ...
   "token": "get_your_token_here"
   ...
 }

  3. Keep this token to authenticate every request you make to a protected endpoint

2 - Authenticate your requests

  1. Fill your Kayrros HTTP Headers and add your token

    header to add

    {
             ...,
             "Authorization": "Bearer {put_your_token_here}"
             ...
            }

  2. Make the request

     curl -X GET \
   https://platform.api.kayrros.com/v1/collection/dataset/summary/{datasetId} \
   -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
   -H 'Cache-Control: no-cache'
authorizationUrl
https://auth.kayrros.com/v3/login

Paths

Collection Datasets

Get dataset metadata

GET /v1/collection/dataset/summary/{datasetId}

Given the ID of a dataset, this API allows you to retreive the metadata of that dataset. You can copy the ID of the dataset from the Collection Dashboard in Kayrros Studio.

Authorization: string
in header

Bearer

datasetId: string
in path

datasetId

200 OK
DatasetMetadata

OK

400 Bad Request

BAD_REQUEST OR VALIDATION_EXCEPTION OR EXCEPTION

401 Unauthorized

WRONG_CREDENTIALS

403 Forbidden

UNAUTHORIZED OR ACCESS_DENIED

404 Not Found

NOT_FOUND

405 Method Not Allowed

METHOD_NOT_ALLOWED

409 Conflict

DUPLICATE_ENTITY

500 Internal Server Error

INTERNAL_SERVER_ERROR

Response Content-Types: */*
Response Example (200 OK) 
{
  "asset_count": "integer (int32)",
  "attributionFile": "string",
  "attributionText": "string",
  "description": "string",
  "id": "string (uuid)",
  "name": "string",
  "processing_id": "string",
  "processing_name": "string",
  "sharedOption": "string",
  "source_id": "string",
  "source_name": "string",
  "start_date": "integer (int64)",
  "stop_date": "integer (int64)"
}
Collection Datasets

Download static dataset

GET /v1/collection/staticdataset/{datasetId}/download

Given the ID of a static dataset, this API allows you to download that dataset. Static datasets can be of different types. You can copy the ID of the dataset from the Collection Dashboard in Kayrros Studio.

authToken: string
in query

Authorization token

Authorization: string
in header

Authorization

datasetId: string
in path

datasetId

200 OK

Returns the file corresponding to the dataset with appropriate content-type header and content-disposition header containing the file name

type
string (byte)
400 Bad Request

BAD_REQUEST OR VALIDATION_EXCEPTION OR EXCEPTION

401 Unauthorized

WRONG_CREDENTIALS

403 Forbidden

UNAUTHORIZED OR ACCESS_DENIED

404 Not Found

NOT_FOUND

405 Method Not Allowed

METHOD_NOT_ALLOWED

409 Conflict

DUPLICATE_ENTITY

500 Internal Server Error

INTERNAL_SERVER_ERROR

Response Content-Types: */*
Response Example (200 OK) 
"string (byte)"
Collection Datasets

Get dataset results

POST /v1/processingresult/dataset/{datasetId}

Given a dataset ID, this API allows you to retreive the content of that dataset. You can copy the ID of the dataset from the Collection Dashboard in Kayrros Studio.

ProcessingResultFilter

processingResultFilter

Authorization: string
in header

Bearer

datasetId: string
in path

datasetId

Request Content-Types: application/json
Request Example
{
  "mo_ids": [
    "string"
  ],
  "time_range": {
    "start_date": "integer (int64)",
    "stop_date": "integer (int64)"
  }
}
200 OK
ProcessingResultTimeSeries

OK

400 Bad Request

BAD_REQUEST OR VALIDATION_EXCEPTION OR EXCEPTION

401 Unauthorized

WRONG_CREDENTIALS

403 Forbidden

UNAUTHORIZED OR ACCESS_DENIED

404 Not Found

NOT_FOUND

405 Method Not Allowed

METHOD_NOT_ALLOWED

409 Conflict

DUPLICATE_ENTITY

500 Internal Server Error

INTERNAL_SERVER_ERROR

Response Content-Types: */*
Response Example (200 OK) 
{
  "assets": [
    {
      "asset_categories": [
        "string"
      ],
      "asset_centroid_latitude": "number (double)",
      "asset_centroid_longitude": "number (double)",
      "asset_id": "string",
      "asset_name": "string",
      "asset_surface_area_m2": "number (double)",
      "asset_version": "integer (int64)",
      "parent_asset_id": "string",
      "parent_asset_name": "string",
      "parent_asset_version": "integer (int64)",
      "results": [
        {
          "metrics": [
            {
              "name": "string",
              "value": "number (double)"
            }
          ],
          "value_date": "string"
        }
      ]
    }
  ],
  "processing_id": "string",
  "source_id": "string"
}

Schema Definitions

AssetResult: object

Processing results for a single asset

asset_categories: string[]
string
asset_centroid_latitude: number (double)
asset_centroid_longitude: number (double)
asset_id: string
asset_name: string
asset_surface_area_m2: number (double)
asset_version: integer (int64)
parent_asset_id: string
parent_asset_name: string
parent_asset_version: integer (int64)
results: Result

results for the asset

Result
Example
{
  "asset_categories": [
    "string"
  ],
  "asset_centroid_latitude": "number (double)",
  "asset_centroid_longitude": "number (double)",
  "asset_id": "string",
  "asset_name": "string",
  "asset_surface_area_m2": "number (double)",
  "asset_version": "integer (int64)",
  "parent_asset_id": "string",
  "parent_asset_name": "string",
  "parent_asset_version": "integer (int64)",
  "results": [
    {
      "metrics": [
        {
          "name": "string",
          "value": "number (double)"
        }
      ],
      "value_date": "string"
    }
  ]
}

DatasetMetadata: object

Collection Dataset Metadata

asset_count: integer (int32)

Number of assets in the dataset

attributionFile: string
attributionText: string
description: string

Dataset Description

id: string (uuid)

Dataset ID

name: string

Dataset Name

processing_id: string

Platform Processing ID used to generate the dataset

processing_name: string

Platform Processing name

sharedOption: string OWNED, SHARED, NON_SHARED

Indicates whether dataset is shared or owned

source_id: string

Platform Source ID used to generate the dataset

source_name: string

Platform Source Name

start_date: integer (int64)

Starting date from which dataset was computed

stop_date: integer (int64)

End date until which dataset was computed

Example
{
  "asset_count": "integer (int32)",
  "attributionFile": "string",
  "attributionText": "string",
  "description": "string",
  "id": "string (uuid)",
  "name": "string",
  "processing_id": "string",
  "processing_name": "string",
  "sharedOption": "string",
  "source_id": "string",
  "source_name": "string",
  "start_date": "integer (int64)",
  "stop_date": "integer (int64)"
}

DateRange: object

Object that represents a date range

start_date: integer (int64)

Start date of the range in epoch milliseconds

stop_date: integer (int64)

End date of the range in epoch milliseconds

Example
{
  "start_date": "integer (int64)",
  "stop_date": "integer (int64)"
}

Metrics: object

Metric representing the numerical result of a processing for a given value_date for an asset

name: string

Metric name/id

value: number (double)

Metric value (numerical)

Example
{
  "name": "string",
  "value": "number (double)"
}

ProcessingResultFilter: object

Filter that can be optionally provided while getting dataset results

mo_ids: string[]

Optional list of asset IDs to which results should be filtered

string
time_range: DateRange

Optional date range to filter the results with

Example
{
  "mo_ids": [
    "string"
  ],
  "time_range": {
    "start_date": "integer (int64)",
    "stop_date": "integer (int64)"
  }
}

ProcessingResultTimeSeries: object

Processing results for a specific source and processing ID

assets: AssetResult

List of asset results for the source and processing IDs

AssetResult
processing_id: string

Processing ID of processing used to generate the results

source_id: string

Source ID from platform

Example
{
  "assets": [
    {
      "asset_categories": [
        "string"
      ],
      "asset_centroid_latitude": "number (double)",
      "asset_centroid_longitude": "number (double)",
      "asset_id": "string",
      "asset_name": "string",
      "asset_surface_area_m2": "number (double)",
      "asset_version": "integer (int64)",
      "parent_asset_id": "string",
      "parent_asset_name": "string",
      "parent_asset_version": "integer (int64)",
      "results": [
        {
          "metrics": [
            {
              "name": "string",
              "value": "number (double)"
            }
          ],
          "value_date": "string"
        }
      ]
    }
  ],
  "processing_id": "string",
  "source_id": "string"
}

Result: object

Represents a single numerical time-series type result

metrics: Metrics

Metrics representing the numerical result

Metrics
value_date: string

Date for which the result applies

Example
{
  "metrics": [
    {
      "name": "string",
      "value": "number (double)"
    }
  ],
  "value_date": "string"
}
Documentation by Spectacle