Dynamic data

VERSION 0.3.1056
PUBLIC PREVIEW

The Dynamic Data module adds real-time information to search results. With dynamic data, users can check whether the right connectors are available for charging their electric vehicles, find the lowest fuel price before stopping to fill up, or know in advance where there are parking places available (and at what price).

Initializing

To use our dynamic data feed, you must configure its credentials and add the SDK as a dependency:

  1. Get your TomTom API Key and configure the project as described in the Project setup guide.
  2. Add the Dynamic data module dependency in the build.gradle of your application module and synchronize the project.
    1dependencies {
    2 implementation "com.tomtom.sdk.search:dynamic-data-online:0.3.1056"
    3}

After synchronizing the project, initialize and use one more of the dynamic data APIs as described below.

EV charging park availability

The EV charging park availability provides information about charging points available at a specified charging park. Initialize the EvChargingAvailabilityProvider object.

evChargingAvailabilityProvider =
OnlineEvChargingAvailabilityProvider.create(context, "YOUR_API_KEY")

The request parameters are defined using EvChargingAvailabilityOptions. The only mandatory parameter is the charging station identifier. You can get this identifier from the search results (see search.) The identifier is a part of SearchResultId of the SearchResult. It has the type EvChargingAvailabilityId.

Not every SearchResult contains charging station information.

You can also add optional restrictions to the request to filter on: connector type, minimum power and maximum power.

1val evChargingAvailabilityOptions =
2 searchResult.searchResultId.evChargingAvailabilityId?.let { chargingAvailabilityId ->
3 EvChargingAvailabilityOptions(
4 chargingAvailabilityId = chargingAvailabilityId,
5 connectorTypeSet = setOf(
6 ConnectorType.Iec62196Type1Ccs,
7 ConnectorType.Iec62196Type3
8 ),
9 minPower = Power.kilowatts(5),
10 maxPower = Power.kilowatts(15)
11 )
12 }

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an EvChargingAvailabilityCallback. A successful request returns EvChargingAvailabilityResponse. If the request fails, a SearchError is returned. The following is an example of the asynchronous charging station availability request call:

1evChargingAvailabilityOptions?.let { options ->
2 evChargingAvailabilityProvider.evChargingStationSearch(
3 options,
4 object : EvChargingAvailabilityCallback {
5 override fun onSuccess(result: EvChargingAvailabilityResponse) {
6 /* YOUR CODE GOES HERE */
7 }
8
9 override fun onError(error: SearchError) {
10 /* YOUR CODE GOES HERE */
11 }
12 }
13 )
14}

Fuel prices

The fuel price request delivers current fuel prices at a specified fuel station. Initialize the FuelPriceProvider object.

fuelPriceProvider = OnlineFuelPriceProvider.create(context, "YOUR_API_KEY")

The request parameters are defined using FuelPriceOptions. The only mandatory parameter is the fuel price identifier. You can get this identifier from the search results (see search.) The identifier is a part of SearchResultId of the SearchResult. It has the type FuelPriceId.

Not every SearchResult contains fuel price information.

1val fuelPriceOptions = searchResult.searchResultId.fuelPriceId?.let { fuelPriceId ->
2 FuelPriceOptions(fuelPriceId)
3}

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an FuelPriceCallback. A successful request returns FuelPriceResponse. If the request fails, a SearchError is returned. The following is an example of the asynchronous fuel price request call:

1fuelPriceOptions?.let { options ->
2 fuelPriceProvider.requestFuelPrices(
3 options,
4 object : FuelPriceCallback {
5 override fun onSuccess(result: FuelPriceResponse) {
6 /* YOUR CODE GOES HERE */
7 }
8
9 override fun onError(error: SearchError) {
10 /* YOUR CODE GOES HERE */
11 }
12 }
13 )
14}

Parking details

The parking details can provide parking prices and parking availability at a specified parking location. Initialize the ParkingDataProvider object.

parkingDataProvider =
OnlineParkingDataProvider.create(context, "YOUR_API_KEY")

Parking availability

The parking availability request provides current information about the number of parking places and the filling trend at the specified parking location. The request parameters are defined using ParkingAvailabilityOptions. The only mandatory parameter is the parking information identifier. You can get this identifier from the search results (see search.) The identifier is a part of SearchResultId of the SearchResult. It has the type ParkingInformationId.

Not every SearchResult contains parking availability information.

1val parkingAvailabilityOptions =
2 searchResult.searchResultId.parkingInformationId?.let { parkingInformationId ->
3 ParkingAvailabilityOptions(parkingInformationId)
4 }

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an ParkingAvailabilityCallback. A successful request returns ParkingAvailabilityResponse. If the request fails, a SearchError is returned. The following is an example of the asynchronous parking availability request call:

1parkingAvailabilityOptions?.let { options ->
2 parkingDataProvider.requestParkingAvailability(
3 options,
4 object :
5 ParkingAvailabilityCallback {
6 override fun onSuccess(result: ParkingAvailabilityResponse) {
7 /* YOUR CODE GOES HERE */
8 }
9
10 override fun onError(error: SearchError) {
11 /* YOUR CODE GOES HERE */
12 }
13 }
14 )
15}

Parking prices

The parking price request provides current parking rate information at the specified parking location. The request parameters are defined using ParkingPriceOptions. The only mandatory parameter is the parking information identifier. You can get this identifier from the search results (see search.) The identifier is a part of SearchResultId of the SearchResult. It has the type ParkingInformationId.

Not every SearchResult contains parking availability information.

In addition to the parking rates, the request can provide a calculated price for the specific request. To receive these results, there are optional parameters defining the parking period that should be configured.

1val parkingPriceOptions =
2 searchResult.searchResultId.parkingInformationId?.let { parkingInformationId ->
3 ParkingPriceOptions(
4 parkingInformationId = parkingInformationId,
5 startTime = Calendar.getInstance(),
6 duration = 3.hours
7 )
8 }

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an ParkingPriceCallback. A successful request returns ParkingPriceResponse. If the request fails, a SearchError is returned. The following is an example of the asynchronous parking price request call:

1parkingPriceOptions?.let { options ->
2 parkingDataProvider.requestParkingPrice(
3 options,
4 object : ParkingPriceCallback {
5 override fun onSuccess(result: ParkingPriceResponse) {
6 /* YOUR CODE GOES HERE */
7 }
8
9 override fun onError(error: SearchError) {
10 /* YOUR CODE GOES HERE */
11 }
12 }
13 )
14}

Next steps

Since you have learned the basics of dynamic data, here are recommendations for the next steps: