Skip to main content
POST
/
v1
/
sdm
/
generate
curl -X POST 'https://api.superseeded.ai/v1/sdm/generate' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "species_name": "Eucalyptus regnans",
    "gcm": "mpi-esm1-2-hr",
    "scenario": "ssp585",
    "period": "2070",
    "include_gradient_maps": true
  }'

{
  "job_id": "7fb88dc37627701681adae8932f85132",
  "status": "queued",
  "message": "Job 7fb88dc37627701681adae8932f85132 has been queued for processing",
  "status_url": "/v1/sdm/status/7fb88dc37627701681adae8932f85132"
}

​
Overview

The SDM (Species Distribution Modeling) endpoints generate predictive models showing where species can survive under current and future climate conditions. The API uses MaxEnt modeling with CHELSA climate data to produce distribution maps.

​
Generate SDM

​
species_name
string
required
Scientific name of the species to model (e.g., “Eucalyptus regnans”)
Species names are automatically validated and corrected using TNRS (Taxonomic Name Resolution Service) before processing. Capitalization errors and minor misspellings are automatically corrected.
​
gcm
string
default:"mpi-esm1-2-hr"
Global Climate Model to use for projectionsAvailable models:
  • mpi-esm1-2-hr
  • ukesm1-0-ll
  • ipsl-cm6a-lr
  • miroc6
  • ec-earth3
​
scenario
string
default:"ssp585"
Emission scenario for future projectionsOptions:
  • ssp126 - Very low emissions
  • ssp245 - Intermediate emissions
  • ssp370 - High emissions
  • ssp585 - Very high emissions
​
period
string
default:"2070"
Future time period for projectionsOptions:
  • 2030 - Near future (2011-2040)
  • 2050 - Mid-century (2041-2070)
  • 2070 - Late century (2071-2100)
​
threshold
number
default:"0.5"
Suitability threshold for classification (0.0 to 1.0)Values above this threshold are considered suitable habitat
​
include_gradient_maps
boolean
default:"true"
Whether to generate gradient suitability maps and trajectory streamplotGenerates:
  • Current climate suitability gradient
  • Future climate suitability gradient
  • Stability trajectory streamplot showing habitat shifts
​
cache_tif_files
boolean
default:"true"
Whether to cache downloaded climate data files for faster subsequent requests

​
Response

​
job_id
string
Unique identifier for the SDM generation job
​
status
string
Current status of the job (queued, processing, completed, failed)
​
message
string
Human-readable status message
​
status_url
string
URL to check job status and retrieve results
curl -X POST 'https://api.superseeded.ai/v1/sdm/generate' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "species_name": "Eucalyptus regnans",
    "gcm": "mpi-esm1-2-hr",
    "scenario": "ssp585",
    "period": "2070",
    "include_gradient_maps": true
  }'

{
  "job_id": "7fb88dc37627701681adae8932f85132",
  "status": "queued",
  "message": "Job 7fb88dc37627701681adae8932f85132 has been queued for processing",
  "status_url": "/v1/sdm/status/7fb88dc37627701681adae8932f85132"
}

​
Check job status

SDM generation typically takes 2-4 minutes to complete depending on the species and data availability.
GET /v1/sdm/status/{job_id}

​
Response fields

​
job_id
string
The job identifier
​
status
string
Current job status (queued, processing, completed, failed)
​
results
object
File paths for generated outputs (when completed)
​
plots
object
Download URLs for visualization files (when completed)Available plots:
  • change_plot - Suitability change map
  • current_gradient - Current climate suitability
  • future_gradient - Future climate suitability
  • trajectory_streamplot - Habitat shift trajectories
​
error
string
Error message if job failed

​
Example response (completed)

{
  "job_id": "7fb88dc37627701681adae8932f85132",
  "status": "completed",
  "results": {
    "change_plot": "/cache/7fb88dc37627701681adae8932f85132/suitability_change_2070.png",
    "current_gradient": "/cache/7fb88dc37627701681adae8932f85132/current_suitability_gradient.png",
    "future_gradient": "/cache/7fb88dc37627701681adae8932f85132/future_suitability_2070_gradient.png",
    "trajectory_streamplot": "/cache/7fb88dc37627701681adae8932f85132/suitability_trajectory_2070.png"
  },
  "plots": {
    "change_plot": "/v1/sdm/download/7fb88dc37627701681adae8932f85132/change_plot",
    "current_gradient": "/v1/sdm/download/7fb88dc37627701681adae8932f85132/current_gradient",
    "future_gradient": "/v1/sdm/download/7fb88dc37627701681adae8932f85132/future_gradient",
    "trajectory_streamplot": "/v1/sdm/download/7fb88dc37627701681adae8932f85132/trajectory_streamplot"
  }
}

​
Download results

GET /v1/sdm/download/{job_id}/{file_type}
Downloads the generated visualization files as PNG images.

​
Available file types

  • change_plot - Shows habitat gain, loss, and stability between current and future climates
  • current_gradient - Current climate suitability map with gradient coloring
  • future_gradient - Future climate suitability map for the specified period
  • trajectory_streamplot - Streamlines showing how suitable habitat areas shift over time

​
Example outputs

​
Suitability change map

Suitability change between current and future climate

​
Current climate gradient

Current climate suitability with occurrence points

​
Future climate gradient

Projected future climate suitability

​
Trajectory streamplot

Habitat shift trajectories over time

​
Example

# Download the trajectory streamplot
curl -X GET 'https://api.superseeded.ai/v1/sdm/download/7fb88dc37627701681adae8932f85132/trajectory_streamplot' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -o trajectory.png

​
Implementation details

The SDM service uses:
  • MaxEnt modeling for species distribution predictions
  • CHELSA v2.1 climate data (1km resolution)
  • GBIF species occurrence records
  • Cloud compute infrastructure (16GB RAM per job)
  • Persistent caching for climate data files
  • Maximum 10 concurrent SDM jobs per API key
  • Each job has a 1-hour timeout
  • Results are cached for 7 days
SDM generation requests are billable events. Each successful job submission counts as one API call for billing purposes.