Place Monitor API

The Lumia Place Monitor API is deprecated. New apps should not use the API as it will not be supported in future devices.

Place Monitor maintains a database of places where the user has spent time: be it working, shopping, enjoying a coffee, or being stuck in a traffic jam.

When motion data is set to the Basic mode, Place Monitor provides data with minimum battery consumption by working passively in the background. This means that the sensor is not actively using GPS to find the location of the device; instead, it uses cell towers and Wi-Fi hotspots to acquire location information. Because Place Monitor obtains location information passively, it does not provide real-time or real-time location information.

When motion data is set to the Detailed mode, Place Monitor uses GPS to accurately locate the device. The sensor uses activity states to optimize GPS usage in order to reduce battery consumption. This means that GPS is used based on how the device is moving. For example, if the activity state is walking, GPS is used in a different way compared to if the activity state is MovingInVehicle.

Place Monitor is able to recognize the following types of places:

• Known
• Frequent
• Home
• Work

The following flow diagram illustrates the logic behind Place Monitor and how places are getting recognized.

A "known" place is first created once the device has stayed in a single location for at least 10 minutes. A single location typically means a circular shape area with a radius of at least 200 meters. The radius may vary over time as the user moves around in the "known" place.

The distance between any two "known" places is typically more than 500 meters. This means that even if there are two or more separate places in a circular area within 500 meter radius of each other, Place Monitor tries to merge these into a single "known" place. In some rare cases, there may be exceptions to this behavior.

Place Monitor classifies those "known" places that users visit often as "frequent" places. The user needs to visit a place at least three times or stay there for a total of over 36 hours for it to become a "frequent" place.

Place Monitor classifies one "frequent" place as "home", and one as "work". The "home" and "work" classification is made after the following criteria:

• A device is in a given 'frequent' place within a certain time interval.
• How much the device moves around and how active the user is.
• How actively the device is used.
• How the device is connected to a charger.

Depending on the user behavior, the classification process typically takes 2-3 days. Apps should note that the classification provides only logical labels for these two places and they may or may not reflect the real meaning of those places. For example, Place Monitor will probably detect school as "work" if school is visited according to the rules of how "work" is recognized. The classification is a best effort and should not be expected to be fully accurate in all device usage scenarios. "Home" and "work" can move over time. For example, if the owner of the device moves to a new address or changes job, the Place Monitor implementation detects this, but in certain cases, the switch might happen only after the old place expires.

Place Monitor adjusts the places list as time goes by. A place that is no longer visited will eventually be removed from the places list. The different place kinds have different expiration times; the "known" kind expires after 10 days, the "frequent" kind after 30 days, and "home" and "work" after 60 days.

The order of the places will change according to the user behavior as well. The places that are visited more often are located higher in the list and places that are visited less are located lower in the list. All new "known" places are added to the top of the list. The speed of the change is based on the user behavior.

Places have the following properties:

• ID is a unique ID for a given place.
• Kind can have the following values: known, frequent, home, or work.
• Position is the geographic position of the place. The accuracy of this position will depend on environmental factors and the consumer's usage.
• Radius is the circular area of the place centered at Position in meters. This represents the uncertainty of the place and will depend on environmental factors and the consumer's usage.
• The time and date when the place was last visited.
• The length of previous visits to the place.
• The total length of all visits to the place.
• The total number of all visits to the place.

Detection accuracy of the places depends on the quality of the location data acquired. When the motion data is set to Basic, the Place Monitor API utilizes only coarse location methods such as cell towers and Wi-Fi hot spots. It is important to note that the detection of places depends on how the consumer is using the device and also on environmental factors, such as the population of cell towers and Wi-Fi hotspots. In areas where there are lot of cell towers and Wi-Fi hotspots, such as city centers, place recognition is more accurate. The center of a "known" place may actually be recognized to be in a somewhat different location than the actual user location. In typical cases, this inaccuracy is within a range of 500 meters, and at best be within about 150 meters. For example, recognized "known" places typically gravitate towards cell towers that were used to determine the device position.

When the motion data is set to Detailed, Place Monitor utilizes mainly GPS to acquire location data. The GPS receiver usage is such that it allows accurate location updates with minimal power consumption. This makes place detection more accurate, timely, and precise. The center of the "Known" place is typically close to the actual user location. In most cases, this is within 100 m. Due to the nature of the low power GPS usage, the detection accuracy degrades somewhat in GPS signal limited environments like deep urban canyons. Place Monitor will also utilize data coming from GPS when the user is using apps that require the use of GPS, for example, navigation apps. In these cases, places data will have a higher accuracy. The active usage of the GPS improves detection accuracy in both Basic and Detailed modes.

If the user has just recently enabled motion data collection, "home" and "work" may not yet be recognized. The developer needs to take into consideration that this information can be missing or may not be correct if the user has an unrecognized working or living pattern.

If an application would like to follow when the device enters or leaves a place it can use
geo-fences.
The application can get a list of places from Place Monitor and create geofences around them. For example, an application could use GetHomeAsync() to get home location and then create a geofence around it.

Examples of how places can look like

Figure: Example visualization of places data.

In the preceding image, green circles represent the radius of the known places, such as home and work. Circles in the pins are symbols for known places.