Link Search Menu Expand Document
Sonos API

ZoneGroupTopologyService

Zone config stuff, eg getting all the configured sonos zones.

The ZoneGroupTopologyService is available on these models: Sonos One (S13) S2 / Sonos Roam (S27) S2 / Sonos Play:5 (S6) S2 / Sonos Sub (Sub) S2 / Sonos Play:1 (S1) S1 / Sonos Play:5 (S5) S1 / Sonos Playbar (S9) S1.

  1. Available actions
    1. BeginSoftwareUpdate
    2. CheckForUpdate
    3. GetZoneGroupAttributes
    4. GetZoneGroupState
    5. RegisterMobileDevice
    6. ReportAlarmStartedRunning
    7. ReportUnresponsiveDevice
    8. SubmitDiagnostics
  2. Events
    1. Subscribe to events
    2. Event variables

Service data

name value
Control URL http://192.168.x.x:1400/ZoneGroupTopology/Control
Event subscription URL http://192.168.x.x:1400/ZoneGroupTopology/Event
Discovery url http://192.168.x.x:1400/xml/ZoneGroupTopology1.xml
Service ID urn:upnp-org:serviceId:ZoneGroupTopology
Service type urn:schemas-upnp-org:service:ZoneGroupTopology:1

Sample request 

POST /ZoneGroupTopology/Control
Host: 192.168.x.x:1400
soapaction: "urn:schemas-upnp-org:service:ZoneGroupTopology:1#{ActionName}"
Content-Type: text/xml; charset="utf-8"

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <s:Body>
    {ActionBodyHere}
  </s:Body>
</s:Envelope>

Available actions

BeginSoftwareUpdate

Action body:

<u:BeginSoftwareUpdate xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
  <UpdateURL>string</UpdateURL>
  <Flags>ui4</Flags>
  <ExtraOptions>string</ExtraOptions>
</u:BeginSoftwareUpdate>

Inputs:

parameter type description
UpdateURL string  
Flags ui4  
ExtraOptions string  

CheckForUpdate

Action body:

<u:CheckForUpdate xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
  <UpdateType>string</UpdateType>
  <CachedOnly>boolean</CachedOnly>
  <Version>string</Version>
</u:CheckForUpdate>

Inputs:

parameter type description
UpdateType string Allowed values: All / Software
CachedOnly boolean  
Version string  

Outputs:

parameter type description
UpdateItem string  

GetZoneGroupAttributes

Get information about the current Zone

Action body:

<u:GetZoneGroupAttributes xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
</u:GetZoneGroupAttributes>

No input arguments

Outputs:

parameter type description
CurrentZoneGroupName string  
CurrentZoneGroupID string  
CurrentZonePlayerUUIDsInGroup string  
CurrentMuseHouseholdId string  

GetZoneGroupState

Get all the Sonos groups, (as XML)

Action body:

<u:GetZoneGroupState xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
</u:GetZoneGroupState>

No input arguments

Outputs:

parameter type description
ZoneGroupState string  

Remarks Some libraries also support GetParsedZoneGroupState that parses the xml for you.

RegisterMobileDevice

Action body:

<u:RegisterMobileDevice xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
  <MobileDeviceName>string</MobileDeviceName>
  <MobileDeviceUDN>string</MobileDeviceUDN>
  <MobileIPAndPort>string</MobileIPAndPort>
</u:RegisterMobileDevice>

Inputs:

parameter type description
MobileDeviceName string  
MobileDeviceUDN string  
MobileIPAndPort string  

ReportAlarmStartedRunning

Action body:

<u:ReportAlarmStartedRunning xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
</u:ReportAlarmStartedRunning>

No input arguments

ReportUnresponsiveDevice

Action body:

<u:ReportUnresponsiveDevice xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
  <DeviceUUID>string</DeviceUUID>
  <DesiredAction>string</DesiredAction>
</u:ReportUnresponsiveDevice>

Inputs:

parameter type description
DeviceUUID string  
DesiredAction string Allowed values: Remove / TopologyMonitorProbe / VerifyThenRemoveSystemwide

SubmitDiagnostics

Action body:

<u:SubmitDiagnostics xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1">
  <IncludeControllers>boolean</IncludeControllers>
  <Type>string</Type>
</u:SubmitDiagnostics>

Inputs:

parameter type description
IncludeControllers boolean  
Type string  

Outputs:

parameter type description
DiagnosticID ui4  

Events

The ZoneGroupTopologyService has variables that might be emitted if you subscribe to events.

Subscribe to events 

SUBSCRIBE /ZoneGroupTopology/Event
Host: 192.168.x.x:1400
callback: <http://...>
NT: upnp:event
Timeout: Second-3600

Event variables

Variable Sends events* type possible values
AlarmRunSequence ✔ string  
AreasUpdateID ✔ string  
AvailableSoftwareUpdate ✔ string  
DiagnosticID   ui4  
MuseHouseholdId ✔ string  
NetsettingsUpdateID ✔ string  
SourceAreasUpdateID ✔ string  
ThirdPartyMediaServersX ✔ string  
ZoneGroupID ✔ string  
ZoneGroupName ✔ string  
ZoneGroupState ✔ string  
ZonePlayerUUIDsInGroup ✔ string  

If the variable has a ✔ in the Sends events column, the service discovery specifies this variable emits events. Other properties might be send as a part of LastChange

This file is automatically generated with @svrooij/sonos-docs, do not edit manually.

Device Software generation Software version Discovery date
Sonos One (S13) S2 63.2-90210 2021-07-21T23:31:19.273Z
Sonos Roam (S27) S2 63.2-90210 2021-07-21T23:31:31.207Z
Sonos Play:5 (S6) S2 63.2-90210 2021-07-21T23:31:45.324Z
Sonos Sub (Sub) S2 63.2-90210 2021-07-21T23:31:40.304Z
Sonos Play:1 (S1) S1 57.6-88280 2021-07-21T14:51:41.469Z
Sonos Play:5 (S5) S1 57.6-88280 2021-07-21T14:51:44.187Z
Sonos Playbar (S9) S1 57.6-88280 2021-07-21T14:51:47.050Z