Every map starts with a location. Use our MCP discovery endpoints to find the location ID you need.
| Type | Description | Examples |
|---|---|---|
country | Sovereign nations | USA, Canada, Mexico |
subdivision | States, provinces, territories | California, Ontario, Oaxaca |
city | Major cities | Los Angeles, Toronto |
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=country'
Response:
{
"success": true,
"data": [
{
"id": "bdd56f14-e776-418a-ab18-89c8138df978",
"name": "United States of America",
"location_code": "us",
"location_type": "country"
},
{
"id": "fde40c8b-4d20-4839-960d-a7685ef3afc0",
"name": "Canada",
"location_code": "ca",
"location_type": "country"
}
]
}
# All subdivisions
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision'
# Search for specific state
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision&q=california'
Response:
{
"success": true,
"data": [
{
"id": "abc123-def456",
"name": "California",
"location_code": "us-ca",
"location_type": "subdivision",
"parent_location_id": "bdd56f14-e776-418a-ab18-89c8138df978"
}
]
}
curl 'https://api.smavatar.com/api/mcp/tools/get-location-details?id=bdd56f14-e776-418a-ab18-89c8138df978'
Response:
{
"success": true,
"data": {
"id": "bdd56f14-e776-418a-ab18-89c8138df978",
"name": "United States of America",
"location_code": "us",
"location_type": "country",
"bounds": {
"minLng": -179.15,
"maxLng": -66.95,
"minLat": 18.91,
"maxLat": 71.35
},
"subdivisions_count": 50
}
}
Location codes follow ISO standards:
| Format | Example | Description |
|---|---|---|
{country} | us, ca, mx | ISO 3166-1 alpha-2 |
{country}-{subdivision} | us-ca, ca-on | ISO 3166-2 |
Here are frequently used location IDs:
| Country | ID | Code |
|---|---|---|
| United States | bdd56f14-e776-418a-ab18-89c8138df978 | us |
| Canada | fde40c8b-4d20-4839-960d-a7685ef3afc0 | ca |
| Mexico | (check API) | mx |
| State | ID | Code |
|---|---|---|
| California | (check API) | us-ca |
| Texas | (check API) | us-tx |
| New York | (check API) | us-ny |
| Florida | (check API) | us-fl |
| Idaho | de340a59-d8c3-419e-ba89-91c60c3335d8 | us-id |
Once you have a location ID, use it in your map request:
curl -X POST '.../jobs/maps' \
-d '{
"location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
"theme": "modern"
}'
To map a specific state/province:
# Get Idaho's location ID
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision&q=idaho'
# Create Idaho map
curl -X POST '.../jobs/maps' \
-d '{
"location_id": "de340a59-d8c3-419e-ba89-91c60c3335d8",
"theme": "modern"
}'