Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Step-by-Step API Implementation Guide

Step-by-step guides for the main API workflows.

Workflow 1: Instant Risk Info ("On-the-Fly")

Best for:

Users who want immediate data without managing a database on our platform.

  1. Authenticate: Obtain your user-specific HTTP Bearer Token from Satelligence.
  2. Prepare Geometry: Define the area you want to check (e.g., a GeoJSON point or polygon). For point geometries plot area can be provided and, to detect risks, we will draw a buffer around the plot based on area provided. If point geometry is provided without area information, we consider by default 4ha area. 
  3. Send Request: Call the get-risk-info endpoint, including your geometry in the request body.
  4. Receive Results: Get an instant JSON response containing risk data for that specific shape.
  5. Analyze & Repeat: Use the data in your internal system. No data is stored on the Satelligence platform. If you need to evaluate the risk across a wider area surrounding the initial polygon, you should consider supplying a second geometry. This secondary geometry would be the result of applying a buffer to the primary geometry. 

Workflow 2: Supply Chain Managed (Plots & Monitoring)

Best for:

Long-term monitoring, frameworks compliance, and supply chain management.

  1. Initiate Upload: Use the bulk-upload endpoint to request a secure upload slot. You will receive a signed URL.

  2. Upload Data: Upload your plot files (GeoJSON) to the signed URL.

    • Tip: Use the Supplier field to tag plots by provider, region, or batch number.
    • Tip: If you want to understand how to deal with plot quality checks go to the section “Advanced workflows: Handling Data Quality and Errors” 
  3. Automatic Quality Check: Our system immediately runs Sanity Checks (validating shapes) and EUDR/TRACES Validation (cross-checking plot coordinates against the declared country).
  4. Monitor Status: Check the status of your upload. Most are processed in minutes; larger datasets may take up to 24 hours.

  5. Access Full Insights: Once "Complete," you can now call get-plot-info to retrieve:

    • Plot results (continuously monitored): containing risk data constantly updated 
    • Geospatial Data: Download shapes in GeoPackage or CSV format.
    • Interactive Maps: Access the plotUrl to view the plot and its 200m buffer zone in a web browser.
    • Get deforestation detections: call the get-plot-detections (deforestation-export)  to retrieve deforestation shapes within your geometries.. 
  6. Manage: Use the API to add new suppliers, update plots, or delete data as your supply chain changes.

Workflow 3: Jurisdictional Risk (Global Data)

Best for:

High-level scouting or regional risk assessment.

  1. Identify Region: Determine the country or administrative region (province/district) you wish to analyze. Currenly we provide insights at the smallest available administrative level per country. We currently deliver insights at the most granular administrative level available within each country.
  2. Query Endpoint: Call the Jurisdictions endpoint using the region’s name or ID.

  3. Retrieve JSON: Receive a pre-computed risk assessment including forest cover trends and the presence of indigenous or protected lands.

    • Note: This workflow does not require you to upload any of your own plot data.

Advanced Workflows

Handling Data Quality & Errors

In real-world supply chains, data isn't always perfect. Our API is designed to be "fail-safe," meaning we stop and alert you if we find issues. However, we also provide a way to bypass non-critical errors so your operations don't grind to a halt.

Proceed with Errors

  • When to use it?
  • When you're uploading large datasets and want to ensure that the "clean" plots are processed even if some other plots in the batch have quality issues.
  • Initiate Bulk Upload: Start your upload as usual. Our system will automatically begin the Sanity Checks (checking for self-intersections, invalid geometries, etc.)
  • Monitor & Inspect: Call the status endpoint to monitor progress. If the system detects issues, it will provide self-explanatory error messages for the specific plots that failed.
  • Evaluate: Review the errors. You might decide that the failed plots are not critical for today’s reporting, or you may want to fix them later.
  • Cancel Upload: Cancel a bulk upload that is in an evaluated state with errors. The upload must have status equal to evaluated and have errors. Use the /bulk-uploads/status endpoint to check the current state before cancelling.

  • Re-upload with proceedWithErrors: You can restart the upload using the proceedWithErrors parameter.

    • What happens next: The platform will ignore the faulty geometries and successfully ingest all valid plots into your database.
    • Result: Your "good" data is live and ready for risk assessment immediately, while you handle the "bad" data separately at your own pace.