Sandworm Tracking API

Monitor, track, and predict sandworm (Shai-Hulud) movements across Arrakis.^🚨

Status:* ✅ Stable - Trusted by spice harvesters for 80+ years^⏳

What are Sandworms?

Sandworms (called "Shai-Hulud" or "Old Man of the Desert" by the Fremen) are massive creatures that patrol the deep desert of Arrakis.^🔍 They are attracted to rhythmic vibrations and are highly territorial.

Key Facts^💡

Size: 100-400 meters in length^❗
Speed: Up to 40 km/h in open sand
Lifespan: Unknown, possibly thousands of years
Attraction: Rhythmic vibrations, especially thumpers^✅
Danger Level: Extreme - can swallow a harvester whole

The Sandworm Object

{
  "id": "worm_shai_hulud_42",
  "estimated_length_meters": 350,
  "estimated_age_years": 800,
  "last_sighting": {
    "timestamp": "10191-07-15T08:45:00Z",
    "location": {"latitude": 22.8, "longitude": -45.1},
    "reported_by": "Fremen scout",
    "confidence": "high"
  },
  "movement_pattern": {
    "direction": "northeast",
    "speed_kmh": 35,
    "predicted_path": [...],
    "erratic_behavior": false
  },
  "fremen_designation": "Old Father",
  "threat_level": "extreme",
  "territorial_range_km": 50,
  "last_fed_hours_ago": 12,
  "rings_visible": 23,
  "has_maker_hooks": false
}

Field Descriptions^🚨

id (string) - Unique worm identifier^❗
estimated_length_meters - Length based on ring count
estimated_age_years - Age estimate (inexact)^🔍
fremen_designation - Name given by Fremen (if known)
rings_visible - Body segment rings (age indicator)^🛠️
has_maker_hooks - Whether worm has been ridden by Fremen^⏳

List Nearby Sandworms

GET /v2/sandworms

Query Parameters

Parameter	Type	Description
	`latitude`	float
`longitude`	float	Center longitude
`radius_km`	float	Search radius (default: 50km, max: 500km)
	`min_size`	integer
`threat_level`	string	`low`, `medium`, `high`, `extreme`
`active_only`	boolean	Only show worms active in last 24 hours
	`fremen_verified`	boolean

Example Request

curl "https://api.spiceflow.arrakis/v2/sandworms?latitude=22.5&longitude=-45.3&radius_km=25" \
  -H "Authorization: Bearer sf_choam_your_key"

Response

{
  "data": [
    {
      "id": "worm_42",
      "estimated_length_meters": 350,
      "distance_from_query_km": 12.5,
      "bearing_degrees": 45,
      "threat_level": "extreme",
      "eta_minutes": 20
    }
  ],
  "warnings": [
    "2 extremely large worms detected within 50km",
    "Coriolis storm may affect worm behavior in next 6 hours"
  ],
  "fremen_advice": "Three worms in formation - very rare. Suggest avoiding area."
}

Get Specific Sandworm

GET /v2/sandworms/{worm_id}

Returns detailed information about a specific sandworm, including movement history and predictions.^💡

Wormsign Prediction^🔍

POST /v2/sandworms/predict

Predict sandworm activity for a given location and time window.

Request Body

{
  "location": {"latitude": 22.5, "longitude": -45.3},
  "time_window_hours": 4,
  "harvest_planned": true,
  "thumper_pattern": "standard"
}

Response

{
  "probability_encounter": 0.65,
  "risk_level": "high",
  "predicted_worms": [
    {
      "id": "worm_42",
      "eta_minutes": 45,
      "confidence": 0.8
    }
  ],
  "recommendations": [
    "Deploy extra thumpers 500m north",
    "Keep carryall on standby",
    "Consider Fremen guide for this operation"
  ],
  "fremen_wisdom": "The worms smell water. Your crew leaks."
}

Note:* Predictions are probabilistic. Always monitor actively during operations.^🚨

Report Wormsign^❗

POST /v2/sandworms/sightings

Report a sandworm sighting (helps improve tracking for everyone).

Request Body

{
  "timestamp": "10191-07-15T09:30:00Z",
  "location": {"latitude": 22.6, "longitude": -45.2},
  "estimated_size": "massive",
  "distance_meters": 800,
  "movement_direction": "northwest",
  "confidence": "high",
  "evidence": {
    "wormsign_observed": true,
    "rhythmic_disturbance": true,
    "sand_displacement": true,
    "thumper_response": "aggressive"
  },
  "reporter_credentials": "harvester_crew_licensed"
}

Response

{
  "id": "sighting_789",
  "verified": true,
  "worm_id": "worm_42",
  "contribution_points": 10,
  "bounty_earned_solaris": 500
}

CHOAM pays 500 solaris per verified wormsign report!^🛠️

Sandworm Behavior Patterns^🔍

GET /v2/sandworms/{worm_id}/behavior

Analyze historical behavior patterns for a specific sandworm.

Response

{
  "worm_id": "worm_42",
  "behaviors": {
    "territorial": true,
    "aggressive_rating": 8.5,
    "thumper_sensitivity": "high",
    "typical_patrol_pattern": "circular",
    "hunting_times": ["dawn", "dusk"],
    "avoids_areas": ["rock_outcroppings", "sietch_tabr_vicinity"]
  },
  "rider_history": {
    "has_been_ridden": true,
    "last_ridden": "10188-03-22",
    "fremen_notes": "Stubborn. Requires experienced rider."
  },
  "danger_assessment": "This worm is particularly aggressive toward harvesters. Recommend 1km safety margin."
}

Thumper Integration^💡

POST /v2/sandworms/thumper-response

Test how a specific sandworm might respond to different thumper patterns.

Request Body

{
  "worm_id": "worm_42",
  "thumper_pattern": "aggressive",
  "thumper_count": 3,
  "thumper_spacing_meters": 200
}

Response

{
  "effectiveness": 0.75,
  "predicted_worm_behavior": "attracted_but_cautious",
  "optimal_harvest_window_minutes": 180,
  "risks": [
    "Worm may investigate thumpers directly",
    "Aggressive pattern may attract additional worms"
  ],
  "fremen_recommendation": "Standard pattern is safer for this worm"
}

Maker Hooks^⏳

GET /v2/sandworms/rideable

Fremen-Only Endpoint* - Requires special authorization.^🚨

Returns sandworms suitable for riding (maker hooks).

Note:* This endpoint is restricted out of respect for Fremen traditions and for safety reasons.^❗

Emergency Alerts^🛠️

Subscribe to automatic wormsign alerts via Webhooks:

client.webhooks.create(
    url="https://yourapp.arrakis/wormsign",
    events=["sandworm.detected", "sandworm.approaching"],
    filters={
        "location_radius_km": 10,
        "min_threat_level": "high"
    }
)

Historical Data^🔍

GET /v2/sandworms/history

Access historical sandworm activity data (useful for pattern analysis).

Query Parameters

region - Geographic region
start_date / end_date - Date range (Imperial calendar)
min_size - Filter by size^✅

Best Practices

Safety First

Never ignore wormsign within 2km^🚨
Always have carryall ready for extraction
Trust Fremen advice - they know the worms best
When in doubt, abort the harvest

Respecting Shai-Hulud^🛠️

The Fremen revere sandworms as sacred. When using this API:

Don't use disrespectful terminology
Honor Fremen knowledge and expertise^💡
Report any worm injuries to Fremen authorities
Never disturb worms unnecessarily

Limitations

Predictions are 70-85% accurate (Fremen intuition is still superior)^🔍
Coriolis storms interfere with tracking
Some worms avoid detection (stealth worms?)^❗
Baby sandworms ("sandtrout") not tracked by this API^✅

Next Steps

"Bless the Maker and His water. Bless the coming and going of Him."* - Fremen prayer^⏳

Sandworm Tracking API

What are Sandworms?

Key Facts 💡

The Sandworm Object

Field Descriptions 🚨

List Nearby Sandworms

Query Parameters

Example Request

Response

Get Specific Sandworm

Wormsign Prediction 🔍

Request Body

Response

Report Wormsign ❗

Request Body

Response

Sandworm Behavior Patterns 🔍

Response

Thumper Integration 💡

Request Body

Response

Maker Hooks ⏳

Emergency Alerts 🛠️

Historical Data 🔍

Query Parameters

Best Practices

Safety First

Respecting Shai-Hulud 🛠️

Limitations

Next Steps

Key Facts^💡

Field Descriptions^🚨

Wormsign Prediction^🔍

Report Wormsign^❗

Sandworm Behavior Patterns^🔍

Thumper Integration^💡

Maker Hooks^⏳

Emergency Alerts^🛠️

Historical Data^🔍

Respecting Shai-Hulud^🛠️