Locations

A Location is a user-defined geolocation such as "Home" or "Office". Locations are a way to group users and devices together to benefit from Automations.

Locations can include hubs, devices, and Automations. Automations can consist of rules, scenes, and SmartApps. Automations allow control of the devices in a Location, the ability to monitor and receive notifications about what's happening at the Location, and more.

A Location can be further organized into Rooms, such as "Kitchen" or "Bedroom".

This article explains how your integration can use our API to create and manage Locations.

Managing Locations

Be aware of the following requirements:

  • A user can belong to 10 Locations. This includes Locations they are invited to and Locations that they own.
  • Each Location can have up to 20 members, including the owner.
  • A Location can have up to 200 devices.

The SmartThings app creates the "My home" Location by default.

Authorization

You must pass an OAuth token in the request header when calling each of the below API methods.

Example

Authorization: Bearer <token>

Location API

List a user's Locations

GET /locations

Call this API to list all Locations currently available in a user account.

OAuth scope: r:locations:*

Example response

{
  "items": [
    {
      "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
      "name": "Home"
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Each Location is returned with its locationId in the items array.

Create a Location

POST /locations

This call creates a Location.

You must include the following parameters in the request body:

In addition to latitude and longitude, you can specify a regionRadius. This is the radius in meters around the latitude and longitude which defines this Location.

If the requested country code is not supported for this Location, then the API will return a 422 error response.

OAuth scope: w:locations:*

Example request

{
  "name": "Home",
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "F",
  "timeZoneId": "American/Chicago",
  "locale": "en"
}

Example response

{
  "locationId": "6b3d1909-1elc-43ec-adc2-5f941de4fbf9",
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "F",
  "timeZoneId": "American/Chicago",
  "locale": "en"
}

Get a Location

GET /locations/<locationId>

This call will return the specified Location by its ID.

You must include a locationId in the URL path.

OAuth scope: r:locations:*

Example response

{
  "locationId": "6b3d1909-1lec-43ec-adc2-5f941de4fbf9",
  "name": "Home", 
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "F",
  "timeZoneId": "America/Chicago",
  "locale": "en"
}

Update a Location

PUT /locations/<locationId>

This call will only update specified fields.

You must include a locationId in the URL path and the Location name in the request body.

OAuth scope: w:locations:*

Example request

{
  "name": "Home", 
  "temperatureScale": "C",
}

Example response

{
  "locationId": "6b3d1909-lelc-43ec-adc2-5f941de4fbf9",
  "name": "Home", 
  "countryCode": "USA",
  "latitude": 45.00708112,
  "longitude": -93.11223629,
  "regionRadius": 150,
  "temperatureScale": "C",
  "timeZoneId": "America/Chicago",
  "locale": "en"
}

Delete a Location

DELETE /locations/<locationId>

This call will delete a Location from a user's account.

You must include a locationId in the URL path.

OAuth scope: w:locations:*

Example response

{}