---
title: "Create a Location"
method: POST
path: "/locations"
tags: ["Locations"]
---

# Create a Location

`POST /locations`

## Request

- Base URL: `https://api.smartthings.com/v1`
- URL: `https://api.smartthings.com/v1/locations`
- Auth: OAuth 2
  - Implicit: `https://auth-global.api.smartthings.com`
  - Scopes: `w:locations:*`
- TypeScript: <https://skmtc.dev/smartthings/apis/smartthings-api/docs/locations/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `allowed` string

## Request body

- CreateLocationRequest
  - `name` string, required: A name given to the Location (e.g. Home)
  - `countryCode` string, required: An ISO Alpha-3 country code (e.g. GBR, USA)
  - `latitude` number: A geographical latitude.
  - `longitude` number: A geographical longitude.
  - `regionRadius` integer: The radius in meters around latitude and longitude which defines this Location.
  - `temperatureScale` string: The desired temperature scale used for the Location. Values include F and C.
  - `timeZoneId` string: 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.
  - `locale` string: We expect a POSIX locale but we also accept an IETF BCP 47 language tag.
  - `additionalProperties` object: Additional information about the Location that allows SmartThings to further define your Location.
  - `parent` LocationParent: The parent of a Location. Intended to be used only in MFU contexts.
    - `type` 'LOCATIONGROUP' | 'ACCOUNT': The type of the Location's parent.
    - `id` string, ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$: The ID of the parent

## Response `200`

Created successfully.

- CreateLocationResponse
  - `locationId` string, required: A unique location identifier. This is not guaranteed to be a valid UUID.
  - `name` string, required: A name given for the location (eg. Home)
  - `countryCode` string, required: An ISO Alpha-3 country code. (i.e. GBR, USA)
  - `latitude` number: A geographical latitude.
  - `longitude` number: A geographical longitude.
  - `regionRadius` integer: The radius in meters around latitude and longitude which defines this location.
  - `temperatureScale` string: The desired temperature scale used within location. Value can be F or C.
  - `timeZoneId` string: 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.
  - `locale` string: We expect a POSIX locale but we also accept an IETF BCP 47 language tag.
  - `backgroundImage` string: Not currently in use.
  - `additionalProperties` object: Additional information about the location that allows SmartThings to further define your location.
  - `parent` LocationParent: The parent of a Location. Intended to be used only in MFU contexts.
    - `type` 'LOCATIONGROUP' | 'ACCOUNT': The type of the Location's parent.
    - `id` string, ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$: The ID of the parent
  - `created` string, date-time: The timestamp of when a location was created in UTC.
  - `allowed` string[]: 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>

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `429`: Too many requests
- `default`: Unexpected error

## Changes

- **2023-11-27** `e8dd260a33ec`: 1 info
  - added the new optional `query` request parameter `allowed`

[Operation history](https://skmtc.dev/smartthings/apis/smartthings-api/changes/locations/post.md)

---

[API](https://skmtc.dev/smartthings/apis/smartthings-api.md) - [All operations](https://skmtc.dev/smartthings/apis/smartthings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartthings/apis/smartthings-api/revisions/2788a4236800?raw)