Developer API

Build with PAP risk intelligence.

Send the same natural-language risk questions users ask inside PAP.EARTH and receive the same live-source forecast payload the dashboard uses.

Endpoint

POST /api/v1/risk

Response

Earth + forecast

Format

JSON

Request

curl -X POST https://www.pap.earth/api/v1/risk \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Assess flood and heat risk for a logistics warehouse in Lagos over the next month",
    "horizon": "30d",
    "decisionLens": "business-setup",
    "alert": {
      "enabled": true,
      "metric": "severity",
      "threshold": 50,
      "hazard": "flood",
      "horizon": "7d",
      "correlationHazards": ["conflict"],
      "correlationThreshold": 30,
      "channels": [{ "type": "webhook", "target": "https://example.com/pap-alerts" }]
    }
  }'

Body Fields

promptstringRequired. A place-based risk question, just like the app search box.

hazardoptionalearthquake, flood, wildfire, heat, storm, air-quality, drought, food-insecurity, conflict.

horizonoptional7d, 30d, 1y, 10y, 30y. Short windows are recommended for operational use.

decisionLensoptionalcommunity-planning, family-relocation, business-setup, travel, investment.

alert.enabledoptionalWhen true, creates a scheduled alert/watch using the same forecast engine.

alert.metricoptionalriskScore, severity, or probability. Use severity for disruption thresholds like 30% or 50%.

alert.hazardoptionalEvent to monitor, such as flood, conflict/war, drought, heat, or earthquake.

alert.horizonoptionalAlert window, such as 7d for the next seven days.

alert.correlationHazardsoptionalTrigger when correlated risks, such as conflict plus food insecurity, cross the correlation threshold.

alert.channelsoptionalWebhook, Slack, Telegram, or email targets. Email queues locally until a delivery provider is configured.

Response

{
  "object": "pap.risk_forecast",
  "riskInput": {
    "hazard": "flood",
    "horizon": "30d",
    "decisionLens": "business-setup"
  },
  "earth": {
    "sceneSpec": { "region": { "name": "Lagos, Nigeria" } },
    "biodiversity": { "source": "gbif", "totalCount": 42 }
  },
  "forecast": {
    "headline": "Flood risk in Lagos, Nigeria",
    "riskScore": 64,
    "confidenceLabel": "medium",
    "dataSources": ["Open-Meteo forecast API", "NASA EONET recent natural events"],
    "practicalGuidance": ["Monitor rainfall thresholds and drainage status."]
  },
  "alertWatch": {
    "id": "lagos-nigeria-flood-lv8...",
    "threshold": 50,
    "alertCondition": {
      "metric": "severity",
      "eventHazards": ["flood"],
      "correlationHazards": ["conflict"]
    }
  }
}