Create Map

API reference for creating map generation jobs.

Create Map Job

Generate a new map by creating a job.

Endpoint

POST /api/v1/projects/{project_id}/jobs/maps

Authentication

Requires API key in Authorization header:

Authorization: Bearer sma_your_api_key

Request Body

{
  "location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
  "width": 1400,
  "height": 900,
  "theme": "modern",
  "output_format": "png",
  "dpi": 72,
  "configuration": {
    "show_subdivision_labels": true,
    "show_country_labels": true
  }
}

Required Fields

Field	Type	Description
`location_id`	string (UUID)	Location to map (get from MCP discovery)

Optional Fields

Field	Type	Default	Description
`width`	number	1400	Image width in pixels (max 4000)
`height`	number	900	Image height in pixels (max 4000)
`theme`	string	`modern`	Visual theme name
`output_format`	string	`png`	Output format: `png` or `svg`
`dpi`	number	72	Resolution (72, 150, or 300)
`configuration`	object	{}	Additional options (see below)

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
`selected_features`	string		Specific feature codes to display
`highlight_subdivisions`	object		Regions to highlight

Response

Success (201 Created)

{
  "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": 50,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Map job created successfully."
}

Error Responses

Location Not Found (404)

{
  "statusCode": 404,
  "message": "Location not found"
}

Invalid Theme (400)

{
  "statusCode": 400,
  "message": "Invalid theme: 'unknown-theme'"
}

Full Example: US Map

Step 1: Find Location ID

curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=country' | jq '.data[] | select(.location_code == "us")'

Returns:

{
  "id": "bdd56f14-e776-418a-ab18-89c8138df978",
  "name": "United States of America",
  "location_code": "us"
}

Step 2: Create Map Job

curl -X POST 'https://api.smavatar.com/api/v1/projects/YOUR_PROJECT_ID/jobs/maps' \
  -H 'Authorization: Bearer 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"
  }'

Step 3: Poll for Completion

curl 'https://api.smavatar.com/api/v1/projects/YOUR_PROJECT_ID/jobs/maps/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Step 4: Get Image URL

When status is completed, construct the URL:

https://hxqvyxnnppomqqwglxwo.supabase.co/storage/v1/object/public/maps/{storage_path}

Rate Limits

20 job creations per hour per API key
Returns 429 Too Many Requests if exceeded

Next Steps

Locations

Find countries, states, and cities.

Highlighting

Create quiz-ready maps with highlighted regions.

Rivers & Lakes

Add hydrological features to your maps.

Overview

Educational map generation API.

Locations

Finding countries, states, and cities for map generation.