Selectors

{"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 and Switch Relay Selectors\"\n}\n[/block]\nSelectors may specify zones which on devices with Zones - the LIFX Z - will act on only those zones. \nThe same syntax is used to target individual relays on a LIFX Switch. On devices without zones or relays, the zone specifications will be ignored.\n\nZones/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.\n\nSome examples of such 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/Relays 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/Relays 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 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. [block:parameters] { "data": { "h-0": "Selector", "h-1": "Returns", "0-0": "`all`", "0-1": "All lights belonging to the authenticated account", "1-0": "`label:[value]`", "1-1": "Lights that match the label.", "2-0": "`id:[value]`", "2-1": "The light with the given id/serial number. Returns a list of one light.", "3-0": "`group_id:[value]`", "3-1": "The lights belonging to the group with the given ID", "4-0": "`group:[value]`", "4-1": "The lights belonging to the groups matching the given label", "5-0": "`location_id:[value]`", "5-1": "The lights belonging to the location matching the given ID", "6-0": "`location:[value]`", "6-1": "The lights belonging to the locations matching the given label", "7-0": "`scene_id:[value]`", "7-1": "The lights that are referenced in the scene with the given ID" }, "cols": 2, "rows": 8 } [/block] [block:api-header] { "type": "basic", "title": "Dynamic Selectors" } [/block] Given the following light: [block:code] { "codes": [ { "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}", "language": "json" } ] } [/block] 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. [block:api-header] { "title": "Multi-zone and Switch Relay Selectors" } [/block] 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: [block:parameters] { "data": { "0-0": "`all|1|2|3|4`", "h-0": "Selector", "h-1": "Returns", "1-0": "`all|1-4`", "1-1": "Equivalent to the previous example", "0-1": "All devices, but acts only on Zones/Relays 1, 2, 3 and 4 of devices with zone support", "2-0": "`location:Kitchen|1|5|9`", "2-1": "All devices in the location with label *Kitchen*, but acts only on Zones/Relays 1, 5 and 9 of devices with zone support" }, "cols": 2, "rows": 3 } [/block]

HTTP Remote Control API

Overview

API Endpoints