Get locations (v1)
POST
https://api.casafari.com/api/v1/references/locationsBearer token6 parameters
On the existing API at https://api.casafari.com (contract clients): send Authorization: Bearer $CASAFARI_TOKEN; see how to get a token. New users: the platform's REST API, platform API keys.
Over MCP: no tool does this. MCP and REST compared.
Description
Returns a list of all possible locations with user restrictions.
Request body
Content type application/json. Optional. Type: object.
namestringLocation name to search.
coordinatesobject[]Limit search to locations within a closed polygon. First and last points must match.
at least 4 items
2 properties
latitudenumberrequiredLatitude.
-90–90
longitudenumberrequiredLongitude.
-180–180
zip_codesstring[]List of zip codes to filter by.
at most 15 items
langstringLanguage to use for the location names in the response. (When the provided language is not supported, the results will be returned in English.)
Example request
Placeholders only: replace the token and the values with your own.
curl -X POST "https://api.casafari.com/api/v1/references/locations" \
-H "Authorization: Bearer $CASAFARI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "ferreiras",
"coordinates": [
{
"longitude": -8.183479,
"latitude": 37.1404
},
{
"longitude": -8.18482,
"latitude": 37.13909
},
{
"longitude": -8.1854,
"latitude": 37.13805
},
{
"longitude": -8.21646,
"latitude": 37.11383
},
{
"longitude": -8.183479,
"latitude": 37.1404
}
],
"lang": "pt"
}'Responses
200 OK
Type: object.
Show the response shape (11 fields)
locationsobject[]requiredList of location objects.
5 properties
location_idintegerrequiredID of the location.
namestringrequiredName of the location.
parent_idintegerrequiredID of the parent level location.
administrative_levelstringrequiredLocation administrative level.
locations_structureobject[]requiredInformation about all the parent locations, starting from the top-most level - country.
5 properties
location_idintegerrequiredLocation ID, as returned by the POST /api/v1/references/locations endpoint.
namestringrequiredLocation name.
administrative_levelstringrequiredLocation administrative level.
zip_codesstring[]The location zip codes.
default []
levelintegerrequiredLocation level as number.
Example from the API description (long arrays shortened)
{
"locations": [
{
"location_id": 1603,
"name": "Ferreiras",
"parent_id": 1602,
"administrative_level": "Freguesia",
"locations_structure": [
{
"location_id": 499,
"name": "Portugal",
"administrative_level": "País",
"zip_codes": [
"1200-224"
],
"level": 1
},
{
"location_id": 1597,
"name": "Faro",
"administrative_level": "Distrito",
"zip_codes": [],
"level": 2
}
]
}
]
}401 Unauthorized
Type: object.
Show the response shape (1 fields)
detailstringDescription of the error encountered.
403 Forbidden
Type: object.
Show the response shape (1 fields)
detailstringDescription of the error encountered.