- Development: external applications and Data Analytics using the Advanced Smart City API
- Authentication to API access, REST Call
- Example: Access to Orion Broker API
- Example: Get Data using Smart City API
- Example of Registering a New User via Mobile App
- Example: Get access token/refresh token via user credentials
- Example: Get access token via refresh token
- Example: Using Advanced Smart City API in Python
- Snap4City Internal API, REST Calls
The external APIs of Snap4City are documented in Swagger: https://www.km4city.org/swagger/external/index.html
Advanced Smart City APIs are:
- Smart City API
- Mainly to get data from the platform
- To access the KB, Service Map resources and query
- Several filtering and capabilities, see also section on Dashboards.
- See this section.
- Orion Broker API, NGSI V2
- Mainly to send/store data/messages on platform via registered entities
- To communicate with Orion Brokers exploiting the Secure Filter of Snap4City.
- See Section IV.C.9
- Entity Directory (IoT Directory) API
- To register new devices, pose queries, etc.
- MyKPI API
- To access (read data, and send data) at MyKPI and other personal data safer
- Heatmap, etc., API
Authentication mechanisms for all of them are reported in Section IV.C.8.
All the Advanced Smart City API may be managed by an API Management system based on APIMAN for accounting and billing if needed to control business, traffic, usage, impose limitations, etc. See: https://www.snap4city.org/827 APIMan management tool can be placed in front of the several APIs to (i) provide a unified entry point, (ii) perform accounting on the API consumption, (iii) placing the basis for providing billing on the basis of API usage and data consumption according to different business models: (a) monthly rate, (b) limits, (c) pay per play, etc. APIMAN may have an integrated SSO with the rest of the Snap4City platform or an independent KeyCloak or other Authentication service connected.
Figure: Smart City API filtering capabilities.
Smart City APIs provide a large number of filtering capabilities as described in training course part 2, and part 4th and summarized in the figure here above.
Each instance of the Snap4City Platform has its own Smart City API, in addition, there is an integrated federated service (called Super) to query all the installations which are federated each other (the federation is decided by each platform owner). Several separated federations may be created as well. Each installation may expose both local Smart City API and Super Smart City API. They have the same syntax but different prefix call.
In each call to the API, you can
- filter by category (nature, Subnature), etc., to obtain a set of devices data and thus also their ServiceURI.
- Retrieve the data of the single Entity Instance (device)/ServiceURI.
- Retrieve the data of a set of Entity Instances (devices)/ServiceURIs.
For example, on using Smart City APIs: (see training slide part 8th)
- Please note that:
- each installation of Snap4City platform may have its own ServiceMap and SUPER to which one can refer. Please ask to your platform administrator.
- via regular Smart city API by category, etc.
- http://svealand.snap4city.org/ServiceMap/api/v1/?selection=59.581458578537955;16.71183586120606;59.62875017053684;16.875171661376957&categories=Street_light&maxResults=100&format=json
- This case is valid for Svealand organization and KB direct access to smart city API
- Via Super
- https://www.disit.org/superservicemap/api/v1/?......
- This case is valid for SUPER on snap4city.org.
- Via Super by values
- https://www.snap4city.org/superservicemap/api/v1/iot-search/?selection=43.77;11.2&maxDists=700.2&model=CarPark
- https://www.snap4city.org/superservicemap/api/v1/iot-search/?selection=42.014990;10.217347;43.7768;11.2515&model=metrotrafficsensor&valueFilters=vehicleFlow>0.5;vehicleFlow<300
- This case is valid for SUPER on snap4city.org.
Time Series are attached to Devices which are identified by ServiceURI. To access at the Time Series (also called real time data) you can:
- From Processing Logic (IoT App) use the block «service info dev». In this case, you automatically access to your private and delegated data. You do not need to perform the authentication since it is performed directly from the microservice Processing Logic (IoT App) context, both on cloud and on edge.
- From Python/Rstudio, Web and Mobile App, you can call Smart City API, see in this section and in Part 7 of the course.
- (1) Retrieve data from Processing Logic (IoT App) and pass them to Python/Rstudio in JSON as presented in other sections, or (2) pass to them only some parameters such as the GPS location and categories. This approach is viable for small amount of data, such as some thousands. For larger amount of data or to be more efficient we suggest using case (2) which is a direct access to the Smart City API from the Data Analytic.
Access to public data does not need to be authenticated, the Smart City API can provide public data without any authentication.
Access to private data from Smart City API can be performed according to the Open ID connect approach. You have to get the Access Token and then perform your API call for query selection as above.
In the following Sections and in the training course sections you can get an example about how to get access to the Private data, and to send data on the platform in the secure manner:
For each Organization on Snap4City.or and for each Organization on any Snap4City installation may provide different: brokers and KB. In addition, for the authentication using OpenID connect as explained in the next section, the so-called client-ID is need. Therefore, please ask to the administrator for your endpoints and clientid, for example:
- Orion broker NGSI V2 url: https://iot-app.snap4city.org/orion-broker-xxxxxx/v2/
- API base url: https://yyyyy.snap4city.org/ServiceMap/api/v1/
- Client id for keycloak: zzzzzzzzidzzzz (the client is public, no client secret is needed)
