Skip to main content

Generate River Guide

Step-by-step guide to generating rivers with the Rivegen API.

Prerequisites​

  • Authenticated API access (see Quickstart)
  • A project or workspace configured

Step 1: Choose Parameters​

Select generation parameters based on your requirements:

{
  "parameters": {
    "length": 1000,        // River length in meters
    "width": 50,          // Average width in meters
    "depth": 10,          // Average depth in meters
    "flow_rate": 100,     // Flow rate (m3/s)
    "terrain_type": "mountain",  // Options: "mountain", "plains", "coastal"
    "season": "spring",   // Options: "spring", "summer", "fall", "winter"
    "generation_method": "ai"
  }
}

Step 2: Start Generation​

const response = await fetch("https://api.rivegen.com/api/rivers/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    project_id: "project_123",
    parameters: {
      length: 1000,
      width: 50,
      depth: 10,
      flow_rate: 100,
      terrain_type: "mountain"
    }
  })
});

const { river_id, status, estimated_completion } = await response.json();

Step 3: Monitor Progress​

Option A: Polling​

async function pollStatus(riverId) {
  while (true) {
    const response = await fetch(
      `https://api.rivegen.com/api/rivers/${riverId}/status`,
      { headers: { Authorization: `Bearer ${TOKEN}` } }
    );
    const data = await response.json();
    
    console.log(`Progress: ${data.progress}%`);
    
    if (data.status === "completed" || data.status === "failed") {
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000)); // Poll every 5s
  }
}
const ws = new WebSocket(
  `wss://api.rivegen.com/ws/rivers/${river_id}/progress?token=${TOKEN}`
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress}%`);
  
  if (data.status === "completed") {
    // Get final results
    fetchRiverData(river_id);
  }
};

Step 4: Retrieve Results​

Once status is "completed":

const response = await fetch(
  `https://api.rivegen.com/api/rivers/${river_id}`,
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);

const riverData = await response.json();
console.log("River data:", riverData.generated_data);

Step 5: Get Visualization​

const vizResponse = await fetch(
  `https://api.rivegen.com/api/rivers/${river_id}/visualization?format=geojson`,
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);

const visualization = await vizResponse.json();
// Use visualization.data for mapping/rendering

Handling Errors​

Generation Failed​

if (riverData.status === "failed") {
  console.error("Generation failed:", riverData.error);
  // Optionally regenerate with different parameters
}

Retry Logic​

async function generateWithRetry(params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await startGeneration(params);
      return result;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Best Practices​

  1. Use WebSocket for real-time updates instead of polling
  2. Store river_id immediately after starting generation
  3. Handle failures gracefully with retry logic
  4. Monitor rate limits when polling frequently
  5. Cache visualization data to reduce API calls

See Also​