Create Map
API reference for map generation.
Create Map
Generate a map by creating a job.
Endpoint
POST /api/v1/projects/{project_id}/jobs/maps
Request
curl -X POST 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/maps' \
-H 'Authorization: Bearer sma_your_api_key' \
-H 'Content-Type: application/json' \
-d '{
"location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
"width": 1400,
"height": 900,
"theme": "modern",
"output_format": "png"
}'
Required Fields
| Field | Type | Description |
|---|---|---|
location_id | string (UUID) | Location to map (see Locations) |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
width | number | 1400 | Width in pixels (400–4096) |
height | number | 900 | Height in pixels (300–2160) |
theme | string | modern | modern, vintage, satellite, monochrome, blueprint |
output_format | string | png | png, svg, or pdf |
dpi | number | 72 | Resolution: 72, 150, or 300 |
configuration | object | {} | Labels, highlighting, features |
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
show_subdivision_labels | boolean | true | Show state/province names |
show_country_labels | boolean | true | Show country name |
show_city_labels | boolean | true | Show city names |
show_features | boolean | false | Show rivers and lakes |
show_river_labels | boolean | false | Show labels on rivers |
show_lake_labels | boolean | false | Show labels on lakes |
river_label_position | string | center | Label position: left, right, top, bottom, center |
lake_label_position | string | center | Label position: left, right, top, bottom, center |
highlight_subdivisions | array | [] | Regions to highlight |
selected_features | array | [] | Specific feature IDs to display |
Response
Success (201)
{
"success": true,
"job": {
"id": "1152f6d1-8df4-4d40-8482-931ff4beb8d3",
"job_type": "map",
"project_id": "your-project-id",
"location": {
"id": "bdd56f14-e776-418a-ab18-89c8138df978",
"code": "us",
"name": "United States of America",
"type": "country"
},
"theme": {
"name": "modern",
"version": "1.0",
"display_name": "Modern Clean Style"
},
"dimensions": {
"width": 1400,
"height": 900,
"dpi": 72
},
"output_format": "png",
"status": "pending",
"estimated_token_cost": 1,
"created_at": "2024-01-15T10:30:00Z"
}
}
Location Not Found (404)
{
"statusCode": 404,
"message": "Location not found"
}
Invalid Theme (400)
{
"statusCode": 400,
"message": "Validation failed: theme must be one of: modern, vintage, satellite, monochrome, blueprint"
}
Check Job Status
curl 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/maps/{job_id}' \
-H 'Authorization: Bearer sma_your_api_key'
Maps complete quickly. When status is "completed", the response includes an assets array.
Download Image
Construct the URL from storage_path:
https://hxqvyxnnppomqqwglxwo.supabase.co/storage/v1/object/public/maps/{storage_path}
Rate Limits
- 60 job creations per hour per API key
See Pricing for token costs.