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

Plots - New!

Operations

Get plots information

Request

This endpoint can be useful in many different situations:

  • Downloading metadata for your plots from the platform
  • Downloading plot geometries from the platform
  • Getting plot-level risk assessments from the platform

It is paginated and returns 200 plots at a time. Use the nextUrl returned in the response to fetch the next page of results.

Security
bearerAuth
Query
projectIdstring

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

supplierstring

Filters plots to those belonging to the supplier with the given satelligence ID.

supplierNamestring

Filters plots to those belonging to the supplier with the given name.

plotNamestring

Filters plots to those with this name.

withGeometryboolean

Whether to include geometry data for each plot. Defaults to false.

cursorstring

Optional pagination cursor for fetching a subsequent page of results.

hasSatelliteMonitoringboolean

Filters plots to those with or without satellite monitoring.

import requests

url = "https://docs.satelligence.com/_mock/api/v1/plots"

query = {
  "projectId": "string",
  "supplier": "string",
  "supplierName": "string",
  "plotName": "string",
  "withGeometry": "true",
  "cursor": "string",
  "hasSatelliteMonitoring": "true"
}

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

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

data = response.json()
print(data)

Responses

Successful response with plot information

Bodyapplication/json
plotsArray of objects
nextUrlstring or null

URL to fetch the next page of results, null if no more result are available.

Response
application/json
{
  "plots": [
    { … }
  ],
  "nextUrl": "string"
}

Get plot information

Request

Security
bearerAuth
Query
projectIdstring

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

withGeometryboolean

Whether to include geometry data for each plot. Defaults to false.

import requests

url = "https://docs.satelligence.com/_mock/api/v1/plots/{id}"

query = {
  "projectId": "string",
  "withGeometry": "true"
}

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

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

data = response.json()
print(data)

Responses

Successful response with plot information

Bodyapplication/json
idstring

Internal satelligence identifier for the plot.

namestring or null

User provided name of the plot.

supplierIdstring

Internal satelligence supplier ID associated with the plot.

supplierNamestring

Supplier name associated with the plot.

hasSatelliteMonitoringboolean or null

Whether satellite monitoring is available for this plot. If the plot is not in your monitoring region, this will be false, and risk information will not be available.

assessmentInfostring or object

Risk assessment information for a plot, can be either a status string or complete risk data.

One of:

Status indicators for plots with no complete assessment

string

Status indicators for plots with no complete assessment

Enum"loading""error""noSatelliteMonitoring"
centerArray of numbers or null

Lng/lat coordinates for the plot. This is not exactly the center or the centroid, but the pole of inaccessibility.

umlIdsArray of strings or null

UML IDs associated with the plot.

producerNamestring or null

User provided ProducerName, if given.

producerCountrystring or null

User provided ProducerCountry, if given.

geometryobject or null

GeoJSON MultiPolygon geometry of the plot, if withGeometry is true.

extraPropertiesobject or null

Any user provided properties you may have given when uploading the plot.

Response
application/json
{
  "id": "string",
  "name": "string",
  "supplierId": "string",
  "supplierName": "string",
  "hasSatelliteMonitoring": true,
  "assessmentInfo": "loading",
  "center": [
    0
  ],
  "umlIds": [
    "string"
  ],
  "producerName": "string",
  "producerCountry": "string",
  "geometry": {},
  "extraProperties": {}
}

Risk Information

Operations

Detections Export

Operations

Projects

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

Operations