> ## Documentation Index
> Fetch the complete documentation index at: https://api.superseeded.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Species Distribution Modeling

> Generate species distribution models and climate suitability maps for any species

## 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

<ParamField body="species_name" type="string" required>
  Scientific name of the species to model (e.g., "Eucalyptus regnans")

  <Note>Species names are automatically validated and corrected using TNRS (Taxonomic Name Resolution Service) before processing. Capitalization errors and minor misspellings are automatically corrected.</Note>
</ParamField>

<ParamField body="gcm" type="string" default="mpi-esm1-2-hr">
  Global Climate Model to use for projections

  Available models:

  * `mpi-esm1-2-hr`
  * `ukesm1-0-ll`
  * `ipsl-cm6a-lr`
  * `miroc6`
  * `ec-earth3`
</ParamField>

<ParamField body="scenario" type="string" default="ssp585">
  Emission scenario for future projections

  Options:

  * `ssp126` - Very low emissions
  * `ssp245` - Intermediate emissions
  * `ssp370` - High emissions
  * `ssp585` - Very high emissions
</ParamField>

<ParamField body="period" type="string" default="2070">
  Future time period for projections

  Options:

  * `2030` - Near future (2011-2040)
  * `2050` - Mid-century (2041-2070)
  * `2070` - Late century (2071-2100)
</ParamField>

<ParamField body="threshold" type="number" default="0.5">
  Suitability threshold for classification (0.0 to 1.0)

  Values above this threshold are considered suitable habitat
</ParamField>

<ParamField body="include_gradient_maps" type="boolean" default="true">
  Whether to generate gradient suitability maps and trajectory streamplot

  Generates:

  * Current climate suitability gradient
  * Future climate suitability gradient
  * Stability trajectory streamplot showing habitat shifts
</ParamField>

<ParamField body="cache_tif_files" type="boolean" default="true">
  Whether to cache downloaded climate data files for faster subsequent requests
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the SDM generation job
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the job (`queued`, `processing`, `completed`, `failed`)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="status_url" type="string">
  URL to check job status and retrieve results
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":"github-dark"}
  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
    }'
  ```

  ```javascript Node.js theme={"theme":"github-dark"}
  const response = await fetch('https://api.superseeded.ai/v1/sdm/generate', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      species_name: 'Eucalyptus regnans',
      gcm: 'mpi-esm1-2-hr',
      scenario: 'ssp585',
      period: '2070',
      include_gradient_maps: true
    })
  });

  const data = await response.json();
  console.log('Job ID:', data.job_id);
  ```

  ```python Python theme={"theme":"github-dark"}
  import requests

  response = requests.post(
      'https://api.superseeded.ai/v1/sdm/generate',
      headers={
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'species_name': 'Eucalyptus regnans',
          'gcm': 'mpi-esm1-2-hr',
          'scenario': 'ssp585',
          'period': '2070',
          'include_gradient_maps': True
      }
  )

  data = response.json()
  print(f"Job ID: {data['job_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"theme":"github-dark"}
  {
    "job_id": "7fb88dc37627701681adae8932f85132",
    "status": "queued",
    "message": "Job 7fb88dc37627701681adae8932f85132 has been queued for processing",
    "status_url": "/v1/sdm/status/7fb88dc37627701681adae8932f85132"
  }
  ```
</ResponseExample>

***

## Check job status

<Note>
  SDM generation typically takes 2-4 minutes to complete depending on the species and data availability.
</Note>

```http theme={"theme":"github-dark"}
GET /v1/sdm/status/{job_id}
```

### Response fields

<ResponseField name="job_id" type="string">
  The job identifier
</ResponseField>

<ResponseField name="status" type="string">
  Current job status (`queued`, `processing`, `completed`, `failed`)
</ResponseField>

<ResponseField name="results" type="object">
  File paths for generated outputs (when completed)
</ResponseField>

<ResponseField name="plots" type="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
</ResponseField>

<ResponseField name="error" type="string">
  Error message if job failed
</ResponseField>

### Example response (completed)

```json theme={"theme":"github-dark"}
{
  "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

```http theme={"theme":"github-dark"}
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

<img src="https://mintcdn.com/superseeded/RejTCL0n2PnsV4CH/images/sdm-examples/change_plot.png?fit=max&auto=format&n=RejTCL0n2PnsV4CH&q=85&s=e16ee74167d6d9f25632f8c0767dadab" alt="Suitability change between current and future climate" width="2277" height="2107" data-path="images/sdm-examples/change_plot.png" />

### Current climate gradient

<img src="https://mintcdn.com/superseeded/RejTCL0n2PnsV4CH/images/sdm-examples/current_gradient.png?fit=max&auto=format&n=RejTCL0n2PnsV4CH&q=85&s=6dc4ee82e409a6ed61de715cbb45b70d" alt="Current climate suitability with occurrence points" width="2401" height="2070" data-path="images/sdm-examples/current_gradient.png" />

### Future climate gradient

<img src="https://mintcdn.com/superseeded/RejTCL0n2PnsV4CH/images/sdm-examples/future_gradient.png?fit=max&auto=format&n=RejTCL0n2PnsV4CH&q=85&s=ef11a978ee2afb8e4c885c5ec8dcacac" alt="Projected future climate suitability" width="2401" height="2064" data-path="images/sdm-examples/future_gradient.png" />

### Trajectory streamplot

<img src="https://mintcdn.com/superseeded/RejTCL0n2PnsV4CH/images/sdm-examples/trajectory_streamplot.png?fit=max&auto=format&n=RejTCL0n2PnsV4CH&q=85&s=5ade4c8dfffa1a7465be1b0ee3ac3dcc" alt="Habitat shift trajectories over time" width="2655" height="2576" data-path="images/sdm-examples/trajectory_streamplot.png" />

### Example

```bash theme={"theme":"github-dark"}
# 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

<Accordion title="Technical architecture">
  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
</Accordion>

<Accordion title="Rate limits">
  * Maximum 10 concurrent SDM jobs per API key
  * Each job has a 1-hour timeout
  * Results are cached for 7 days
</Accordion>

<Accordion title="Billing">
  SDM generation requests are billable events. Each successful job submission counts as one API call for billing purposes.
</Accordion>