{"__v":3,"_id":"55f28173f9f3991900f38a1b","category":{"__v":1,"_id":"55f28172f9f3991900f38a15","pages":["55f28173f9f3991900f38a17","55f28173f9f3991900f38a18","55f28173f9f3991900f38a19","55f28173f9f3991900f38a1a","55f28173f9f3991900f38a1b","55f28173f9f3991900f38a1c"],"project":"54ebb40d6423300d003672c0","version":"55f28172f9f3991900f38a13","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-17T04:27:26.544Z","from_sync":false,"order":1,"slug":"overview","title":"Overview"},"project":"54ebb40d6423300d003672c0","user":"557e2561eb75d80d00af3dab","version":{"__v":2,"_id":"55f28172f9f3991900f38a13","project":"54ebb40d6423300d003672c0","createdAt":"2015-09-11T07:23:30.065Z","releaseDate":"2015-09-11T07:23:30.065Z","categories":["55f28172f9f3991900f38a14","55f28172f9f3991900f38a15","55f28172f9f3991900f38a16","55f66acb297b37170058accb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"updates":["566f43f97ffa002300c3cd76"],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T05:04:55.069Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"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\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 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.","excerpt":"Controlling which lights will be operated on for a request.","slug":"selectors","type":"basic","title":"Selectors"}

Selectors

Controlling which lights will be operated on for a request.

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. 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 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.