This use case allows the delivery by the providers of real-time information on the availability of parking spaces.
This use case aims to collect and publish in a centralized and homogeneous way the information in real time related to car parks in Spanish cities. Agents/interested third parties can consume the information by subscribing. It allows suppliers to send information to the DGT 3.0 platform on the availability of parking spaces in real time. Consumers will be able to publish the information in their information systems accessible by the end user, allowing them to better plan their trips and consider the use of public transport.
The platform has two different functionalities for the publication (sending) and for the subscription (reception) of information. The first is through a REST API and the second through a real-time MQTT service.
Both the publication and subscription functionality require different access certificates that must be requested and supplied by DGT 3.0. If these certificates have not already been requested, they should be requested from soporte@cmobility30.es.
Below are the URLs with which each functionality is accessed:
Mode | URL | Description |
---|---|---|
Publication | https://pre.cmobility30.es/use-case-11 | Client integration environment endpoint for publishing (certain publishing methods will be accessible for consumption) |
Subscription | mqtt://mqtt.pre.cmobility30.es:8883 | Integration environment endpoint for subscription |
The two functionalities are described below.
Publication
This use case has a REST API for the publication (sending) of the data by the companies that request it. Details of this can be found in the following sections:
- General details for making a request:
- Information regarding the event to be sent:
Subscription
This use case also has a subscription service (reception) to the data for the companies that request it through the MQTT protocol. Below you can find the details of this:
MQTT (MQ Telemetry Transport) is a messaging protocol used as a simple and lightweight method to transfer data to / from low-power devices.
The protocol supports a single messaging pattern, the Publish-Subscribe pattern: each message is published on a topic that must be subscribed to in order to receive the information.
Subscription to the service of this use case must be through the topic:
usecase11/free/{cityIne}
The parameter cityIne is the identifier of the municipality where the event is generated according to the INE, it refers to the municipality in which the event takes place, therefore each municipality will have its own specific topic.
In the topic, the events are published in JSON format. Here you can see an example:
{
"cityIne":50297,
"parkingId":1,
"free":14,
"capacity":158,
"timestamp":"2021-03-15T13:34:00.000Z"
}
-
cityIne (integer): identifier of the municipality where the event is generated according to the INE
-
parkingId (integer): parking identifier.
-
free (integer): number of free parking spaces.
-
capacity (integer): total parking capacity.
-
timestamp (date UTC): date and time in UTC format of the moment in which the car park was updated for the last time. It needs to not be a future timestamp with respect to the current UTC time. The date must end with the character 'Z' that marks that it is in UTC.
See more information and a connection example here.
In addition, subscribers will also be able to access the following REST API publication methods to obtain information:
- Information regarding the methods of this use case:
Note: The information that is being published in the development environment is a simulation with non-real information that changes throughout the day, so that the consumption interface can be tested.
Errors
As stated above, all HTTP responses other than 200 – OK, can be considered invalid. The format of the error response is like the following example:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
These errors will have three main categories:
Authentication Error
-
HTTP Status: 401 - Unauthorized
Code Message 1 User not found or valid
Client Error
-
HTTP Status: 400 - Bad Request
-
Code Message 0 Authenticate 2 Entity ID not found 3 Missing required property 4 The entity received cannot be proccessed 5 Incorrect token received 6 Expired token received 7 There is an error with the token provided. Please request a new one 8 No token received 9 Required request body is missing 10 Event is marked as expired by timestamp 11 Missing request header 12 Access denied role 13 Unique key violated. In the INE code XXX, the first parking Id available is YYY. 14 There is an error in one or more elements 15 Free capacity should not be greater than total capacity 16 Invalid GeoJson 17 GeoJson does not belong to municipality 18 Timestamp can not be future 19 Day of week not valid. Allowed values: 'L','M','X','J','V','S','D' 20 TimeTable should not have duplicated days 21 Inconsistent time range: startTime should be before endTime 22 Inconsistent time range: there is a crossing schedule 23 There was an error when creating the Datex II file 24 There are no parkings in municipality or the provided INE code is not correct
In the case of getting an error 3 - Missing required property, the response obtained will have a value in the message that will indicate the missing fields to send:
{
"status": 400,
"code": 3,
"message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
}
Server error
-
HTTP Status: 500 - Internal Server Error
Code Message 25 Internal error