Locations
Find countries, states, and cities.
Locations
Every map starts with a location. Use the discovery endpoint to find location IDs.
Location Types
| Type | Description | Examples |
|---|---|---|
country | Sovereign nations | USA, Canada, Mexico |
subdivision | States, provinces | California, Ontario |
city | Major cities | Los Angeles, Toronto |
Discover Locations
List Countries
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"
}
]
}
List Subdivisions
# All subdivisions
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision'
# Search by name
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision&q=california'
# Filter by parent
curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision&parent_id=bdd56f14-e776-418a-ab18-89c8138df978'
Response:
{
"success": true,
"data": [
{
"id": "ba4f6c29-283a-4eae-bbe9-a9cd0e0ecbdb",
"name": "California",
"location_code": "us-ca",
"location_type": "subdivision",
"parent_location_id": "bdd56f14-e776-418a-ab18-89c8138df978"
}
]
}
Get Location Details
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
}
}
}
Location Codes
Codes follow ISO standards:
| Format | Example | Standard |
|---|---|---|
{country} | us, ca, mx | ISO 3166-1 alpha-2 |
{country}-{subdivision} | us-ca, ca-on | ISO 3166-2 |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
type | string | country, subdivision, or city |
q | string | Search by name or code |
parent_id | string (UUID) | Filter by parent location |
limit | number | Max results (default: 50, max: 100) |
Use in Map Request
Once you have a location ID:
curl -X POST '.../jobs/maps' \
-d '{
"location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
"theme": "modern"
}'