SMsmartthings
Locations

Create a Location

Changed on

Create a Location for a user. The Location will be created geographically close to the country code provided in the request body. If Location creation is not supported in the requested country code, the API will return a 422 error response with an error code of UnsupportedGeoRegionError.

post/locations

Request

Query parameters

allowedstring

If set to true, the response may contain the allowed list property. Note that setting this to true may significantly slow the response time. If you are creating a location for your own account, then you know you will have all these permissions and can avoid the trouble of passing in this parameter.

Request body

namestring required

A name given to the Location (e.g. Home)

countryCodestring required

An ISO Alpha-3 country code (e.g. GBR, USA)

latitudenumber

A geographical latitude.

longitudenumber

A geographical longitude.

regionRadiusinteger

The radius in meters around latitude and longitude which defines this Location.

temperatureScalestring

The desired temperature scale used for the Location. Values include F and C.

timeZoneIdstring

An ID matching the Java Time Zone ID of the location. If this is not provided, the service will try to choose a time zone based on the latitude and longitude.

localestring

We expect a POSIX locale but we also accept an IETF BCP 47 language tag.

additionalPropertiesobject

Additional information about the Location that allows SmartThings to further define your Location.

Example request

{
  "name": "Home",
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "F",
  "timeZoneId": "America/Chicago",
  "locale": "en_US",
  "parent": {
    "type": "LOCATIONGROUP",
    "id": "6ecb6c06-7319-49b1-8ebd-f97660efdd06"
  }
}

Response

Created successfully.

locationIdstring required

A unique location identifier. This is not guaranteed to be a valid UUID.

namestring required

A name given for the location (eg. Home)

countryCodestring required

An ISO Alpha-3 country code. (i.e. GBR, USA)

latitudenumber

A geographical latitude.

longitudenumber

A geographical longitude.

regionRadiusinteger

The radius in meters around latitude and longitude which defines this location.

temperatureScalestring

The desired temperature scale used within location. Value can be F or C.

timeZoneIdstring

A valid Java Time Zone ID for the location. This can be specified in the create request, or it can be generated based on the latitude and longitude.

localestring

We expect a POSIX locale but we also accept an IETF BCP 47 language tag.

backgroundImagestring

Not currently in use.

additionalPropertiesobject

Additional information about the location that allows SmartThings to further define your location.

createdstring date-time

The timestamp of when a location was created in UTC.

allowedstring[]

List of client-facing action identifiers that are currently permitted for the user. If the value of this property is not null, then any action not included in the list value of the property is currently prohibited for the user. If the value of this property is null (or absent), then no permission-related information is being provided.

<ul> <li> w:locations - the user can change the name of the location <li> d:locations - the user can delete the location <li> w:grants:locationshare - the user can share the location with other users <li> w:devices - the user can create devices on the location <li> w:locations:geo - the user can edit the geo-coordinates of the location <li> r:installedapps - the user can view or list installed apps on the location <li> w:installedapps - the user can create installed apps on the location <li> r:modes - the user can view or list Modes on the location <li> r:rooms - the user can view or list rooms on the location <li> w:rooms - the user can create rooms on the location <li> r:locations:currentmode - the user can view the current Mode on the location <li> w:locations:currentmode - the user can change the current Mode on the location <li> r:scenes - the user can view or list scenes on the location <li> w:scenes - the user can create scenes on the location <li> r:rules - the user can view or list rules on the location <li> w:rules - the user can create rules on the location <li> r:linkedplaces - the user can view or list linked places on the location <li> w:linkedplaces - the user can create linked places on the location <li> r:hubmanager - the user can launch the hub manager <li> w:hubmanager - the user can edit the hub manager <li> r:cameras:clips - the user can view video clips associated with camera devices on the location <li> w:cameras:clips - the user can record video clips associated with camera devices on the location </ul>

Example response

{
  "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
  "name": "Home",
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "F",
  "timeZoneId": "America/Chicago",
  "locale": "en_US",
  "parent": {
    "type": "LOCATIONGROUP",
    "id": "6ecb6c06-7319-49b1-8ebd-f97660efdd06"
  },
  "created": 1547920800
}

Changes