Skip to content

Satelligence API (v1)

The satelligence API provides 4 capabilities to synchronize data to and from the platform:

  1. Bulk uploads new!

A full fledged set of endpoints to manage supply chain data in the platform. Use this endpoint to set up automated data synchronization of supply chain data to the Satelligence platform and fully leverage the risk assessment and mitigation features inside the platform.

  1. Plot downloads new!

An endpoint that can serve to sync plot data from the platform into your own systems. It can serve both plot metadata, geometries, and risk assessments from the platform.

  1. Get Risk Info

A lightweight endpoint to access geospatial risk information for a given boundary without uploading supply chain data to the platform. Use this endpoint to leverage the Satelligence geospatial data but build your own risk assessment and mitigation strategies outside of the Satelligence platform.

  1. Detections export

To fetch all deforestation and fire detections in shapefile format. Use this endpoint to gather the raw Satelligence real time data and build your own archive of detections for fully custom workflows.

Authentication

Authentication requires an API token, contact support@satelligence.com to request one. To authenticate your requests, set the Authorization: Bearer $token header in your requests.

The token is connected to a personal account, it will have the same permissions as the account that created it. If the linked user belongs to multiple projects, the token will default to the 'active project' for that user.

Languages
Servers
Mock server

https://docs.satelligence.com/_mock/api/

Production server

https://api.satelligence.com/

Bulk Uploads - New!

These endpoints give full control over supply chain data uploads and ingestion.

For a bulk upload, plots must be formatted as a GeoJSON file and uploaded to a secure location in Satelligence's Google Cloud Storage bucket through a signed URL. The complete process consists of three steps:

  1. Create a bulk upload with the POST /bulk-uploads endpoint, which generates signed URLs for each file you want to upload.
  2. Use the signed URLs to upload the files to the required place for this upload.
  3. Start the bulk upload with the POST /bulk-uploads/start endpoint.

The process can be automated with the scripts linked here.

Operations

Create a bulk upload

Request

This endpoint generates signed URLs needed to upload plot files. The signed URLs are valid for 60 minutes. Any uploaded files for which an upload is not started within the 60 minute timeframe are deleted.

After calling this endpoint, you need to upload each file to the provided Google Cloud Storage URLs. To do this with cURL, you can use:

curl -X PUT --upload-file $path_to_file $your_signed_url -H 'Content-Type: application/octet-stream'

Examples showing how to do this in Python and Javascript can be found in the example scripts.

The endpoint returns an uploadId that needs to be given to the /bulk-uploads/start endpoint to trigger the upload, after uploading the plot files to the signed URLs.

Security
bearerAuth
Bodyapplication/jsonrequired
projectIdstring

Project ID (optional, defaults to user's 'active project')

supplierstringrequired

Supplier name. Currently bulk uploads are only supported for one supplier at a time.

Example: "Lumon Industries"
fileNamesArray of strings

List of file names to upload. If none is are provided, a single signed URL will be returned.

import requests

url = "https://docs.satelligence.com/_mock/api/v1/bulk-uploads"

payload = {
  "projectId": "string",
  "supplier": "Lumon Industries",
  "fileNames": [
    "string"
  ]
}

headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <YOUR_TOKEN_HERE>"
}

response = requests.post(url, json=payload, headers=headers)

data = response.json()
print(data)

Responses

Successful generation of signed URLs

Bodyapplication/json
uploadIdstring

ID of the upload. Store this id to use it for the /start and /status endpoints.

Example: "556cd039-90c6-4091-9720-c761746f5972"
signedUrlsArray of objects
Response
application/json
{
  "uploadId": "556cd039-90c6-4091-9720-c761746f5972",
  "signedUrls": [
    { … }
  ]
}

Start a bulk upload

Request

Start processing a bulk upload with a given upload ID. Allows choosing whether to overwrite existing data or not.

This endpoint validates constraint on the uploaded files:

  • Less than 100 files can be uploaded at a time
  • Total size of all files must be less than 2GB

Note: only one upload can be in progress for a given supplier at a time. If you try to start an upload for a supplier that already has an upload in progress, you will get a '429 Too Many Requests' error, and will have to retry later.

Security
bearerAuth
Bodyapplication/jsonrequired
uploadIdstring(uuid)required

ID of the upload to initiate

overwriteboolean

Whether to overwrite existing data

import requests

url = "https://docs.satelligence.com/_mock/api/v1/bulk-uploads/start"

payload = {
  "uploadId": "ef523ba8-509e-47af-8e2c-5fa751596497",
  "overwrite": True
}

headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <YOUR_TOKEN_HERE>"
}

response = requests.post(url, json=payload, headers=headers)

data = response.json()
print(data)

Responses

Upload initiated successfully

Bodyapplication/json
statusstring

Status of the initiation request

uploadIdstring

ID of the initiated upload

messagestring

Success message

Response
application/json
{
  "status": "string",
  "uploadId": "string",
  "message": "string"
}

Get upload status

Request

Retrieves the status of a particular bulk upload, or lists all the ongoing uploads in the given project.

If an uploadId is provided, this endpoint returns information about that upload: what stage it is at, if any errors were encountered.

If no uploadId is provided, this endpoint returns a list of the ongoing uploads for the given project, which can be useful to get a view of everything currently uploading in a given project. If the projectId is not set this uses the user's active project.

Security
bearerAuth
Query
uploadIdstring(uuid)

ID of the upload to check

projectIdstring(uuid)

(optional) ID of the project to list ongoing uploads for.

import requests

url = "https://docs.satelligence.com/_mock/api/v1/bulk-uploads/status"

query = {
  "uploadId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

headers = {"Authorization": "Bearer <YOUR_TOKEN_HERE>"}

response = requests.get(url, headers=headers, params=query)

data = response.json()
print(data)

Responses

Successful response with upload status

Bodyapplication/json
statusstring

Current status of the upload

createdAtstring

Timestamp when the upload was created

errorMessagesArray of strings

Error messages if the upload failed

isOverwriteboolean

Whether this upload is an overwrite operation

Response
application/json
{
  "status": "string",
  "createdAt": "string",
  "errorMessages": [
    "string"
  ],
  "isOverwrite": true
}

Plots - New!

Operations

Risk Information

Operations

Detections Export

Operations

Projects

These endpoints provide access to project information, useful for organizations with multiple projects.

Operations