{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Selectors","type":"basic","slug":"selectors","excerpt":"Controlling which lights will be operated on for a request.","body":"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.\n\nSelectors 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.\n\nSelectors 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`.\n\nYou can determine which values to use by inspecting the response from the lights endpoint.\n\nGenerally, 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.\n\nAll selectors return a list for consistency, even `id`.\n\nYou 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. \n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Selector\",\n \"h-1\": \"Returns\",\n \"0-0\": \"`all`\",\n \"0-1\": \"All lights belonging to the authenticated account\",\n \"1-0\": \"`label:[value]`\",\n \"1-1\": \"Lights that match the label.\",\n \"2-0\": \"`id:[value]`\",\n \"2-1\": \"The light with the given id/serial number. Returns a list of one light.\",\n \"3-0\": \"`group_id:[value]`\",\n \"3-1\": \"The lights belonging to the group with the given ID\",\n \"4-0\": \"`group:[value]`\",\n \"4-1\": \"The lights belonging to the groups matching the given label\",\n \"5-0\": \"`location_id:[value]`\",\n \"5-1\": \"The lights belonging to the location matching the given ID\",\n \"6-0\": \"`location:[value]`\",\n \"6-1\": \"The lights belonging to the locations matching the given label\",\n \"7-0\": \"`scene_id:[value]`\",\n \"7-1\": \"The lights that are referenced in the scene with the given ID\"\n },\n \"cols\": 2,\n \"rows\": 8\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Dynamic Selectors\"\n}\n[/block]\nGiven the following light:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"id\\\": \\\"d3b2f2d97452\\\",\\n \\\"label\\\": \\\"Left Lamp\\\",\\n \\\"group\\\": {\\n \\\"id\\\": \\\"1c8de82b81f445e7cfaafae49b259c71\\\",\\n \\\"name\\\": \\\"Lounge\\\",\\n },\\n \\\"location\\\": {\\n \\\"id\\\": \\\"1d6fe8ef0fde4c6d77b0012dc736662c\\\",\\n \\\"name\\\": \\\"Home\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nYou can reference the light with the following selectors:\n\n * `id:d3b2f2d97452`\n * `label:Left Lamp`\n * `group_id:1c8de82b81f445e7cfaafae49b259c71`\n * `group:Lounge`\n * `location_id:1d6fe8ef0fde4c6d77b0012dc736662c`\n * `location:Home`\n\nWhen 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.\n[block:api-header]\n{\n \"title\": \"Multi-zone Selectors\"\n}\n[/block]\nSelectors may specify zones which on devices with Zones - the LIFX Z - will act on only those zones. On devices without zones the zone specifications will be ignored.\n\nZones are specified via a `|`-separated suffix to the device selector: a specific zone 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.\n\nSome examples of zone selectors:\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"`all|1|2|3|4`\",\n \"h-0\": \"Selector\",\n \"h-1\": \"Returns\",\n \"1-0\": \"`all|1-4`\",\n \"1-1\": \"Equivalent to the previous example\",\n \"0-1\": \"All devices, but acts only on Zones 1, 2, 3 and 4 of devices with zone support\",\n \"2-0\": \"`location:Kitchen|1|5|9`\",\n \"2-1\": \"All devices in the location with label *Kitchen*, but acts only on Zones 1, 5 and 9 of devices with zone support\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]","updates":["566f43f97ffa002300c3cd76"],"order":4,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"55f28173f9f3991900f38a1b","project":"54ebb40d6423300d003672c0","user":"557e2561eb75d80d00af3dab","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["55f28172f9f3991900f38a14","55f28172f9f3991900f38a15","55f28172f9f3991900f38a16","55f66acb297b37170058accb","5d229ff5e59b8e003ab3a9da"],"_id":"55f28172f9f3991900f38a13","project":"54ebb40d6423300d003672c0","releaseDate":"2015-09-11T07:23:30.065Z","createdAt":"2015-09-11T07:23:30.065Z","__v":3},"__v":4,"category":{"sync":{"isSync":false,"url":""},"pages":["55f28173f9f3991900f38a17","55f28173f9f3991900f38a18","55f28173f9f3991900f38a19","55f28173f9f3991900f38a1a","55f28173f9f3991900f38a1b","55f28173f9f3991900f38a1c"],"title":"Overview","slug":"overview","order":1,"from_sync":false,"reference":false,"_id":"55f28172f9f3991900f38a15","version":"55f28172f9f3991900f38a13","__v":1,"createdAt":"2015-06-17T04:27:26.544Z","project":"54ebb40d6423300d003672c0"},"createdAt":"2015-06-17T05:04:55.069Z","githubsync":"","parentDoc":null}
Selectors
Controlling which lights will be operated on for a request.