International Telecommunication Union ITU-T Technical Specification TELECOMMUNICATION STANDARDIZATION SECTOR (7 April 2019) OF ITU ITU-T Focus Group on Data Processing and Management to support IoT and Smart Cities & Communities Technical Specification D3.2 SensorThings API – Sensing FOREWORD The International Telecommunication Union (ITU) is the United Nations specialized agency in the field of telecommunications, information and communication technologies (ICTs). The ITU Telecommunication Standardization Sector (ITU-T) is a permanent organ of ITU. ITU-T is responsible for studying technical, operating and tariff questions and issuing Recommendations on them with a view to standardizing telecommunications on a worldwide basis. The procedures for establishment of focus groups are defined in Recommendation ITU-T A.7. ITU-T Study Group 20 set up the ITU-T Focus Group on Data Processing and Management to support IoT and Smart Cities & Communities (FG-DPM) at its meeting in March 2017. ITU-T Study Group 20 is the parent group of FG-DPM. Deliverables of focus groups can take the form of technical reports, specifications, etc., and aim to provide material for consideration by the parent group in its standardization activities. Deliverables of focus groups are not ITU-T Recommendations. ITU 2019 All rights reserved. No part of this publication may be reproduced, by any means whatsoever, without the prior written permission of ITU. Technical Specification D3.2 SensorThings API – Sensing Summary The SensorThings API provides an open, geospatial-enabled and unified way to interconnect the Internet of Things devices, data, and applications over the Web. The SensorThings API is an open standard, and that means it is non-proprietary, platform-independent, and perpetual royalty-free. Although it is a new standard, it builds on a rich set of proven-working and widely-adopted open standards, such as the Web protocols and the OGC Sensor Web Enablement (SWE) standards, including the ISO/OGC Observation and Measurement data model [OGC 10-004r3 and ISO 19156:2011]. That also means the SensorThings API is extensible and can be applied to not only simple but also complex use cases. The SensorThings API – Sensing provides a standard way to manage and retrieve observations and metadata from heterogeneous IoT sensor systems. The SensorThings API follows the REST principles, the use of an efficient JSON encoding, the use of MQTT protocol, the use of the flexible OASIS OData protocol and URL conventions. Acknowledgements This Technical Specification was researched and principally authored by Steve Liang (Open Geospatial Consortium), Tania Khalafbeigi (SensorUp and University of Calgary) under supervision of Gyu Myoung Lee (Korea, Rep.of). Additional information and materials relating to this Technical Specification can be found at: www.itu.int/go/tfgdpm. If you would like to provide any additional information, please contact Denis Andreev at [email protected]. Keywords Internet of things; iot; ogc; sensor web; smart cities; smart communities Technical Specification D3.2 SensorThings API – Sensing Table of Contents 1 Scope ............................................................................................................................. 1 2 References ..................................................................................................................... 1 3 Definitions ..................................................................................................................... 1 3.1 Terms defined elsewhere ................................................................................ 1 3.2 Terms defined in these Technical Specifications ........................................... 2 4 Abbreviations and acronyms ......................................................................................... 2 5 Conventions .................................................................................................................. 3 6 The SensorThings API Entities ..................................................................................... 3 6.1 Common Control Information ........................................................................ 3 6.2 The Sensing Entities ....................................................................................... 4 6.2.1 Thing ............................................................................................................... 5 6.2.2 Location .......................................................................................................... 6 6.2.3 HistoricalLocation .......................................................................................... 8 6.2.4 Datastream ...................................................................................................... 9 6.2.5 Sensor ............................................................................................................. 12 6.2.6 ObservedProperty ........................................................................................... 14 6.2.7 Observations ................................................................................................... 15 6.2.8 FeatureOfInterest ............................................................................................ 17 7 SensorThings Service Interface .................................................................................... 18 7.1 Common Control Information ........................................................................ 19 7.2 Resource Path ................................................................................................. 19 7.2.1 Usage 1: no resource path ............................................................................... 19 7.2.2 Usage 2: address to a collection of entities ..................................................... 21 7.2.3 Usage 3: address to an entity in a collection ................................................... 22 7.2.4 Usage 4: address to a property of an entity ..................................................... 23 7.2.5 Usage 5: address to the value of an entity’s property ..................................... 23 7.2.6 Usage 6: address to a navigation property (navigationLink) .......................... 24 7.2.7 Usage 7: address to an associationLink .......................................................... 24 7.2.8 Usage 8: nested resource path ......................................................................... 25 7.3 Requesting Data .............................................................................................. 26 7.3.1 Evaluating System Query Options .................................................................. 26 7.3.2 Specifying Properties to Return ...................................................................... 26 7.3.3 Query Entity Sets ............................................................................................ 29 8 SensorThings Sensing Create-Update-Delete ............................................................... 36 8.1 Overview ......................................................................................................... 36 8.2 Create an entity ............................................................................................... 36 8.2.1 Request ........................................................................................................... 36 8.2.2 Response ......................................................................................................... 39 8.3 Update an entity .............................................................................................. 40 8.3.1 Request ........................................................................................................... 40 8.3.2 Response ......................................................................................................... 41 8.4 Delete an entity ............................................................................................... 41 8.4.1 Request ........................................................................................................... 41 9. Batch Requests .............................................................................................................. 42 9.1 Introduction ..................................................................................................... 42 9.2 Batch-processing request ................................................................................ 42 9.2.1 Batch request body example ........................................................................... 43 9.2.2 Referencing new entities in a change set example ......................................... 45 9.3 Batch-processing response .............................................................................. 46 9.4 Asynchronous batch requests ......................................................................... 48 10. SensorThings MultiDatastream extension .................................................................... 50 11. SensorThings Data Array Extension ............................................................................. 56 11.1 Retrieve a Datastream’s Observation entities in dataArray ............................ 56 11.1.1 Request ........................................................................................................... 57 11.1.2 Response ......................................................................................................... 57 11.2 Create Observation