Batch Processing & Utilities
Batch natal charts, timezone utilities, and system information endpoints.
Overview
Utility endpoints for batch processing, timezone management, and system information queries.
POST /ephemeris/natal/batch
Calculate multiple natal charts in a single request.
Request Body
{
subjects: SubjectRequest[]; // Array of subjects
configuration?: NatalConfig; // Shared configuration
options?: ResponseOptions; // Shared options
}
Response
{
success: true;
charts: NatalChartResponse[]; // Ordered results
total_count: number;
processing_time_ms: number;
metadata: {
successful: number;
failed: number;
errors: Array<{
index: number;
error: string;
}>;
};
}
Example
curl -X POST https://api.astromcp.io/ephemeris/natal/batch \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"subjects": [
{
"name": "Person 1",
"birth_datetime": { "iso": "1990-01-01T12:00:00" },
"birth_location": {
"latitude": { "decimal": 40.7128 },
"longitude": { "decimal": -74.0060 },
"timezone": { "iana_name": "America/New_York" }
}
},
{
"name": "Person 2",
"birth_datetime": { "iso": "1992-06-15T14:30:00" },
"birth_location": {
"latitude": { "decimal": 34.0522 },
"longitude": { "decimal": -118.2437 },
"timezone": { "iana_name": "America/Los_Angeles" }
}
}
],
"configuration": {
"house_system": "P",
"zodiac_type": "tropical"
}
}'
Use Cases
- Family charts: Calculate charts for entire family
- Synastry analysis: Get charts for relationship analysis
- Research: Process multiple birth data sets
- Database imports: Bulk calculation for stored subjects
Performance
- Limit: 50 subjects per request
- Processing: ~200-500ms per chart
- Parallel: Charts calculated concurrently
- Ordering: Results match input order
POST /timezone/lookup
Get IANA timezone for geographic coordinates.
Request Body
{
latitude: { decimal: number };
longitude: { decimal: number };
}
Response
{
timezone: string; // IANA timezone (e.g., "America/New_York")
latitude: number;
longitude: number;
fallback: boolean; // true if using nearest timezone
}
Example
curl -X POST "https://api.astromcp.io/timezone/lookup" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"latitude": { "decimal": 40.7128 },
"longitude": { "decimal": -74.0060 }
}'
POST /timezone/offset
Get UTC offset for coordinates at a specific datetime (handles DST).
Request Body
{
latitude: { decimal: number };
longitude: { decimal: number };
datetime: { iso: string };
}
Response
{
timezone: string;
utc_offset: number; // Seconds from UTC
dst_active: boolean;
latitude: number;
longitude: number;
}
Example
curl -X POST "https://api.astromcp.io/timezone/offset" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"latitude": { "decimal": 40.7128 },
"longitude": { "decimal": -74.0060 },
"datetime": { "iso": "2024-07-15T12:00:00Z" }
}'
Use Cases
- Historical charts: Get correct timezone for past dates
- DST handling: Automatically account for daylight saving
- Offset conversion: Convert local time to UTC
- Validation: Verify timezone data for birth times
GET /ephemeris/house-systems
List all supported house systems.
Response
{
house_systems: Array<{
code: string; // "P", "K", etc.
name: string;
description: string;
origin: string;
}>;
}
Example Response
{
"house_systems": [
{
"code": "P",
"name": "Placidus",
"description": "Most popular system in modern Western astrology",
"origin": "17th century"
},
{
"code": "W",
"name": "Whole Sign",
"description": "Ancient system, each house = one sign",
"origin": "Hellenistic period"
}
]
}
GET /ephemeris/supported-objects
List all supported celestial bodies.
Response
{
bodies: Array<{
name: string;
category: string; // "planet", "asteroid", "node", "point"
traditional: boolean;
modern: boolean;
}>;
total_count: number;
}
Categories
Planets: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
Nodes: North Node, South Node
Points: Chiron, Lilith (mean/true), Vertex, Part of Fortune
Asteroids: Ceres, Pallas, Juno, Vesta
GET /health
Basic health check for the API.
Response
{
status: "healthy" | "degraded" | "unhealthy";
timestamp: string;
version: string;
}
GET /health/detailed
Detailed system status and metrics.
Response
{
status: "healthy" | "degraded" | "unhealthy";
services: {
ephemeris: {
status: string;
latency_ms: number;
};
database: {
status: string;
latency_ms: number;
};
cache: {
status: string;
hit_rate: number;
};
};
metrics: {
requests_per_minute: number;
average_latency_ms: number;
error_rate: number;
};
system: {
uptime_seconds: number;
memory_usage_mb: number;
cpu_usage_percent: number;
};
}
Use Cases
- Monitoring: Track API health
- Cold starts: Detect when service is warming up
- Performance: Check latency metrics
- Debugging: Diagnose service issues
GET /version
Get API version information.
Response
{
version: string; // e.g., "2.0.1"
release_date: string;
endpoints_count: number;
changelog_url: string;
}
Best Practices
Batch Processing
- Chunk large datasets: Process in batches of 25-50
- Handle failures gracefully: Check metadata.errors array
- Cache results: Store calculated charts to avoid recalculation
- Rate limits: Respect per-minute limits
Timezone Handling
- Always use IANA timezones: Not UTC offsets
- Store timezone with birth data: For future recalculations
- Validate coordinates: Ensure valid ranges (-90 to 90 lat, -180 to 180 lng)
- Handle DST: Use /timezone/offset for specific dates
System Monitoring
- Check /health/detailed before critical operations
- Monitor cold starts: Degraded status may indicate warming up
- Track error rates: Investigate if error_rate > 5%
- Cache health checks: Don't query every request
Related Endpoints
- Natal Charts - Single chart calculation
- Location Services - Coordinate lookup
- API Overview - Complete endpoint list