Selectors

Selectors are an identifier for addressing one or many lights belonging to the authenticated account. The most broad selector is all and the most narrow is id:d3b2f2d97452. Selectors with many lights will return an array of light objects, selectors with one light will return a light object.

Selectors can be static or dynamic. Static selectors are formatted as value and are the same for all lights. all is an example of a static selector. Dynamic selectors are formatted as type:value and the values are based on the current state of the lights. id:d3b2f2d97452 is an example of a dynamic selector.

Selectors which generally specify multiple lights, all, group, group_id, location, location_id, and scene_id, accept an optional suffix :random which specifies a single random light from that set of lights. e.g. all:random, group:[value]:random, location_id:[value]:random.

You can determine which values to use by inspecting the response from the lights endpoint.

Generally, you should avoid using label-based selectors (label, group, location) when developing an application as they will break if users rename the label, group or location. They are provided as convenient helpers for personal-level projects.

All selectors return a list for consistency, even id.

You can combine up to 25 selectors together additively by separating them with ,, so if you want to address both a light labelled "Bedroom" and a light labelled "Office", you can use label:Bedroom,label:Office as the selector.

Selector	Returns
`all`	All lights belonging to the authenticated account
`label:[value]`	Lights that match the label.
`id:[value]`	The light with the given id/serial number. Returns a list of one light.
`group_id:[value]`	The lights belonging to the group with the given ID
`group:[value]`	The lights belonging to the groups matching the given label
`location_id:[value]`	The lights belonging to the location matching the given ID
`location:[value]`	The lights belonging to the locations matching the given label
`scene_id:[value]`	The lights that are referenced in the scene with the given ID

Dynamic Selectors

Given the following light:

{
  "id": "d3b2f2d97452",
  "label": "Left Lamp",
  "group": {
    "id": "1c8de82b81f445e7cfaafae49b259c71",
    "name": "Lounge",
  },
  "location": {
    "id": "1d6fe8ef0fde4c6d77b0012dc736662c",
    "name": "Home"
  }
}

You can reference the light with the following selectors:

```
`id:d3b2f2d97452`
```
```
`label:Left Lamp`
```

`group_id:1c8de82b81f445e7cfaafae49b259c71`

```
`group:Lounge`
```

`location_id:1d6fe8ef0fde4c6d77b0012dc736662c`

```
`location:Home`
```

When using group or location selectors you'll also reference other lights in the same group or location. Take care to correctly encode parameters when using selectors.

Multi-zone and Switch Relay Selectors

Selectors may specify zones which on devices with Zones - the LIFX Z - will act on only those zones.
The same syntax is used to target individual relays on a LIFX Switch. On devices without zones or relays, the zone specifications will be ignored.

Zones/Relays are specified via a |-separated suffix to the device selector: a specific zone or relay is specified by just the number of that zone, between 0 and 255. A zone range is specified as M-N where both M and N are zone numbers between 0 and 255, M <= N, and the endpoint zones are included.

Some examples of such selectors:

Selector	Returns
`all\|1\|2\|3\|4`	All devices, but acts only on Zones/Relays 1, 2, 3 and 4 of devices with zone support
`all\|1-4`	Equivalent to the previous example
`location:Kitchen\|1\|5\|9`	All devices in the location with label Kitchen, but acts only on Zones/Relays 1, 5 and 9 of devices with zone support