Simulation API

Generate emergency scenarios and test system performance

Simulation Endpoint

Generate realistic emergency scenarios for testing and training purposes with access911.

Endpoint

POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate

Request

Headers

Header	Type	Required	Description
Content-Type	string	Yes	application/json
Accept	string	No	application/json

Body Parameters

Parameter	Type	Required	Default	Description
scenario	string	No	la_wildfire	Emergency scenario to simulate
num_calls	integer	No	1	Number of emergency calls to generate (1-1000)
table_name	string	No	wildfire-simulation-calls	DynamoDB table name

Available Scenarios

Scenario ID	Name	Description
la_wildfire	Los Angeles Wildfire	Wildfire emergency simulation
nashville_tornado	Nashville Tornado	Tornado outbreak simulation
earthquake_sf	San Francisco Earthquake	Earthquake emergency simulation
hurricane_florida	Florida Hurricane	Hurricane emergency simulation

Request Examples

Basic Simulation

curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "nashville_tornado",
    "num_calls": 25
  }'

High-Volume Simulation

curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "la_wildfire",
    "num_calls": 100,
    "table_name": "emergency-calls"
  }'

Custom Table Simulation

curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "earthquake_sf",
    "num_calls": 50,
    "table_name": "test-emergency-calls"
  }'

Response

Success Response

{
  "message": "Generated 25 calls for Nashville Tornado Outbreak",
  "scenario": "nashville_tornado",
  "total_requested": 25,
  "successful": 25,
  "failed": 0,
  "generation_method": "Templates (fast mode)",
  "sample_calls": [
    {
      "call_id": "NASHVILLE_TORNADO-1703123456-1234",
      "location": "Downtown Nashville",
      "emergency_type": "building_damage"
    },
    {
      "call_id": "NASHVILLE_TORNADO-1703123457-1235",
      "location": "East Nashville",
      "emergency_type": "trapped_person"
    }
  ],
  "errors": []
}

Error Response

{
  "error": "Unknown scenario: invalid_scenario",
  "available_scenarios": [
    "la_wildfire",
    "nashville_tornado",
    "earthquake_sf",
    "hurricane_florida"
  ]
}

Response Fields

Field	Type	Description
message	string	Success message describing the operation
scenario	string	The scenario that was simulated
total_requested	integer	Number of calls requested
successful	integer	Number of calls successfully generated
failed	integer	Number of calls that failed to generate
generation_method	string	Method used for generation (“Bedrock AI” or “Templates (fast mode)“)
sample_calls	array	Sample of generated calls (first 5)
errors	array	List of any errors encountered

HTTP Status Codes

Code	Description
200	Success - Calls generated successfully
400	Bad Request - Invalid parameters or scenario
500	Internal Server Error - Server error during processing

Rate Limits

• Maximum calls per request: 1000
• Rate limit: 100 requests per minute
• Burst limit: 500 requests per minute

Generation Methods

AI-Powered Generation (≤20 calls)

For small batches, the API uses AWS Bedrock AI to generate human-like call summaries:

{
  "generation_method": "Bedrock AI",
  "quality": "High",
  "processing_time": "2-5 seconds"
}

Template-Based Generation (>20 calls)

For large batches, the API uses templates for high throughput:

{
  "generation_method": "Templates (fast mode)",
  "quality": "Good",
  "processing_time": "1-3 seconds"
}

Call Data Structure

Each generated call includes:

{
  "call_id": "NASHVILLE_TORNADO-1703123456-1234",
  "timestamp": 1703123456,
  "created_at": "2023-12-21T10:30:56.789Z",
  "location": {
    "latitude": "36.1627",
    "longitude": "-86.7816",
    "address": "1234 Broadway, Downtown Nashville",
    "area": "Downtown Nashville"
  },
  "emergency_type": "building_damage",
  "severity": "critical",
  "description": "severe structural damage from tornado",
  "summary": "Caller reported severe structural damage from tornado at 1234 Broadway, Downtown Nashville. Fire and EMS units dispatched to scene.",
  "duration_secs": 180,
  "caller_phone": "[phone]",
  "status": "active",
  "simulation": true,
  "scenario": "nashville_tornado",
  "scenario_name": "Nashville Tornado Outbreak"
}

Error Handling

Common Errors

Error	Description	Solution
Unknown scenario	Invalid scenario ID provided	Use one of the available scenarios
Invalid num_calls	Number of calls out of range	Use a number between 1 and 1000
DynamoDB error	Database operation failed	Check table permissions and configuration
Bedrock error	AI generation failed	Falls back to template generation

Error Response Format

{
  "error": "Error description",
  "details": "Additional error information",
  "timestamp": "2023-12-21T10:30:56.789Z"
}

Best Practices

Performance Optimization

• Start Small: Begin with 10-20 calls to test system responsiveness
• Monitor Performance: Watch response times and error rates
• Use Appropriate Scenarios: Choose scenarios that match your testing needs

Error Handling

• Implement Retry Logic: Retry failed requests with exponential backoff
• Handle Rate Limits: Implement proper rate limiting in your client
• Monitor Errors: Track error rates and types for debugging

Security

• Validate Input: Always validate parameters before sending requests
• Handle Sensitive Data: Be careful with sensitive information in logs
• Use HTTPS: Always use HTTPS for API requests

SDK Examples

Python

import requests
import json

def generate_emergency_calls(scenario, num_calls):
    url = "https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate"
    payload = {
        "scenario": scenario,
        "num_calls": num_calls
    }
    
    response = requests.post(url, json=payload)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API Error: {response.status_code} - {response.text}")

# Usage
result = generate_emergency_calls("nashville_tornado", 25)
print(f"Generated {result['successful']} calls")

JavaScript

async function generateEmergencyCalls(scenario, numCalls) {
  const url = 'https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate';
  const payload = {
    scenario: scenario,
    num_calls: numCalls
  };
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Error generating calls:', error);
    throw error;
  }
}

// Usage
generateEmergencyCalls('nashville_tornado', 25)
  .then(result => console.log(`Generated ${result.successful} calls`))
  .catch(error => console.error('Error:', error));

Testing

Unit Testing

import unittest
from unittest.mock import patch, Mock

class TestSimulationAPI(unittest.TestCase):
    def test_successful_simulation(self):
        with patch('requests.post') as mock_post:
            mock_response = Mock()
            mock_response.status_code = 200
            mock_response.json.return_value = {
                "successful": 25,
                "failed": 0
            }
            mock_post.return_value = mock_response
            
            result = generate_emergency_calls("nashville_tornado", 25)
            self.assertEqual(result["successful"], 25)
            self.assertEqual(result["failed"], 0)

Integration Testing

# Test basic functionality
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{"scenario": "nashville_tornado", "num_calls": 5}'

# Test error handling
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{"scenario": "invalid_scenario", "num_calls": 5}'

Testing Environment: Use the simulation API for testing and training purposes only. For production emergency response, ensure proper integration with your existing 911 systems.