Location History API Service Basics
&w=256&q=90)
TomTom Location History API services offer the ability to build applications based on object location histories. The Location History service can potentially be used for managing vehicle fleets, handling optimal taxi pickup locations, and for delivering on-demand services. This article introduces you to some of the concepts behind location history services and provides an overview of the services and endpoints provided by the Location History APIs.
When we think about location-based applications, we're often thinking in terms of where people, places, and items are right now. Then we might take that a step further and think about how we get from here to there.
Another useful application of location information is keeping track of where things have been over time. Knowing where objects have been can be useful information for assessing past performance and making decisions on future routes. Geofencing applications are based on location history. They keep track of whether an item tracked is inside or outside of some virtual boundary, or fence. The location history is a record of an object’s location, speed, and direction.
TomTom Location History API services offer the ability to build applications based on object location histories. The service handles secure collection and storage of location information. The location history is available to anything with an Internet connection. The Location History service can potentially be used for managing vehicle fleets, handling optimal taxi pickup locations, and for delivering on-demand services.
This article introduces you to some of the concepts behind location history services and provides an overview of the services and endpoints provided by the Location History APIs.
Geofences
Location history is built on two concepts: objects and geofences.
Objects are pretty simple. They are things or, sometimes, people that report their location to the Location History service.
Geofences are virtual boundaries defined within the mapping service. Geofences are not required for using location history, but geofences can be used with location history to enable transitions.
A geofence can be defined in a number of different ways. A simple fence could be defined by a location and a radius. This forms a circular fence. Or a geofence could be defined by a pathway and some distance from this pathway, or by providing two coordinates that are opposite corners of a rectangle, or more complex geofences defined by a series of coordinates. You can learn more by reading the Geofencing API documentation or the article [link article here when published].
Objects
As mentioned earlier, objects are various types of things that one might want to track: vehicles, packages, and people are examples of objects. But the possibilities are not limited to these.
An object will need some way of communicating its location. This means that an Internet connection is required. The connection could be direct, as might be the case with a smartphone or a vehicle with an inbuilt mobile connection, or the connection could be indirect as might be the case of an IoT device with limited connectivity that reports locations only occasionally.
Every asset tracked must also be uniquely identifiable. There may be other information about the object to be saved alongside its identifier. For a vehicle this could be the make, model, color, or fleet ID, route, or driver.
Objects are defined in the Location History API as we'll explain later in this article.
Location History
An object periodically reports its location: its latitude, longitude, and elevation. Over time an object will make several location reports. The saved reports for a specific object make up its location history.
From an object’s location history the general path that the object followed could be reconstructed. Tracing through the reconstructed path estimates of the speed and direction can be made.
This information powers scenarios such as knowing when a delivery vehicle is within a range of a warehouse so that its packages can be moved to a loading dock before arrival. Or it could be to know that a tracked asset has been moved outside of an authorized area. For a geofence it may also be necessary to know what assets are with it, such as how many trucks are at a pickup side. With multiple geofenced areas, one could analyze which areas or routes are most popular for, say, taxi pickups during certain times of day.
Archiving Information
For many location history applications, the information that is most frequently needed will also be the information that is relatively recent. You can imagine that a location history service can collect vast amounts of data. Knowledge of where an asset has been over the past several weeks may be more demanded than where an object was several months ago.
The more recent history will need to be in storage that is available for immediate retrieval the be consumed by applications, analyzed, or to track an object’s last known position. As an item of location information ages it may not need to be accessed as frequently, but it might still need to be retained.
A planned addition to the service is the ability to move older information of lower demand to archives. Once archived, the information is still available but will have to be retrieved from archives to be used.
About the Location History
TomTom provides several services to assist you with collecting and managing location history. These services are accessible through the developer portal at https://developer.tomtom.com.
The Location History API enables you to manage location history projects and administrators, object, geofences, and more.
At the top of the Location History service is the concept of project administration. People and applications that have access to location history can be given different roles, which includes isolating some roles from potentially sensitive location information of other objects and entities that are interacting with location history. Considering who has access to what information is a good way to start any Location History-powered project.
With the Requester role, a person or application has access to read location history, but doesn’t have access to update or alter it. A Requester can also ask for the most recently reported positions of tracked objects to get an idea of where those objects are now.
Administrators have full rights to create, update, and delete location history. Only Administrators have rights to access archived location information.
Restricting entities to specific roles helps to better assure the integrity of the data and confidentiality of the information stored. An account for a tracked asset cannot be used to access the data on other tracked assets.
The Configuration Service
For both Location History and Geofencing, the Configuration service is used for managing privacy settings and generating administrative keys. Keys can be created, updated, and revoked through this service. The Configuration service also provides information for the options set on an account.
The maximum number of objects that can be tracked and the maximum number of geofences that can exist in an account can be read through this service.
The Position History Service
The Position History service is used by the assets reporting their location information. To build location history, an application periodically communicates its location back to the TomTom Position History service. The position information reported by different devices are stored separately from each other. It is retrievable only by accounts that are authorized to read it.
The service provides the last known location of the objects (good for assessing where things are right now) and the location history of an object over a time range. Deleting the position history information for a specific object before a date is also performed through the Position History service.
The Archive Service
Reported location information is considered active and immediately available for up to three months. Active information is available for immediate access. Location information within a requested date range is available through a request to the Position History service.
Location history more than three months old is archived. Archived data is available for up to nine months.
In an archived state the information isn’t requested by a date range. Instead the information is made available through a zip file that contains the entirety of the archived location data. This information must be prepared before being downloaded.
The general pattern for downloading archive location information is for an application to first tell the Archive service that it wishes to download the information. The service will then begin preparing the information. The application that requested the archive location information can periodically check the status of its request. When the archive is prepared the application will see its status and begin downloading it.
Next Steps
As you've seen, location history is built from the location updates that an object post as they move between geofenced areas. The location information is securely collected and stored. Tracked assets and entities don’t have access to the location information of others within the same system.
Tracking where objects have been, and how they move about, can be a valuable resource for your organization. Give it a try and see what scenarios unfold.
To learn more about the Location History API, check out these related articles:
* Required field. By submitting your contact details to TomTom, you agree that we can contact you about marketing offers, newsletters, or to invite you to webinars and events. We could further personalize the content that you receive via cookies. You can unsubscribe at any time by the link included in our emails. Review our privacy policy.