location/history

Contents

URL

Description

Retrieves the current user's location history, by date range or bounding box.

Note: By default, all apps created after August 13, 2013 do not store location history for their users. If you would like to enable this feature, please contact [email protected] to request access. You will need to be able to demonstrate your application's need for storing and retrieving history, and we will work with you to find a paid plan that can accommodate your needs.

Supported Request Methods

GET

Output Formats

json, xml, gpx, kml

By default, location history is returned in JSON format. Optionally history can be returned in GPX or KML formats. To specify a different output format, append the file extension to the end of the path, for example, location/history.gpx.

Parameters

Optional

count (default: 10)

Return the most recent n points of history

location/history?count=100

after

Return points more recent than the given timestamp. Dates should be given in iso8601 format or as a unix timestamp.

location/history?after=1280340811

before

Return points older than the given timestamp. Dates should be given in iso8601 format or as a unix timestamp.

location/history?before=1280340811

sort (default: asc) asc or desc

Sort the points returned in ascending or descending order. If you're retrieving the latest 500 points, you should sort by "desc" but if you're downloading historical data in chunks you should probably sort by "asc".

location/history?after=1280340811&sort=asc

accuracy (default: 150)

Return points with an accuracy greater than the given value. Rough location fixes from the cell tower will usually have an accuracy of 500 meters, so querying data more accurate than 200 meters will give you good results.

location/history?accuracy=200

thinning (default: 0)

The "thinning" parameter will thin the history data by 1/n so you get slightly less accurate data but it will be spread out over a longer period of time. For example, if the user records 100 points in an hour, and you set thinning to 2, returning the last 100 points will return data logged in the last 2 hours. The points are chosen at random, so you will get slightly different results if you run this repeatedly. Set to "0" or omit the parameter to turn thinning off.

geometry

If you want to query points by geometry, set this parameter to the type of geometry you're specifying. circle or rectangle are the two modes that are currently supported. Some of the below parameters will be required based on the search type.

location/history?geometry=circle&center=45.511,-122.633&radius=0.5 or location/history?geometry=rectangle&sw=45.504,-122.653&ne=45.512,-122.644

center Required for geometry=point

When querying for data within a circle, specify the center of the circle in the format lat,long.

radius Required for geometry=point

When querying for data within a circle, specify the radius of the circle in meters.

sw Required for geometry=rectangle

When querying for data within a rectangle, specify the southwest corner of the rectangle in the format lat,long.

ne Required for geometry=rectangle

When querying for data within a rectangle, specify the northeast corner of the rectangle in the format lat,long.

ignore_gaps (default: 0)

By default, the query will attempt to identify "gaps" in the location stream and will only return points for the last trip up to the gap. This should make things look better when plotted onto the map. To disable this behavior, set this parameter to 1

no_points Optional

If no_points=1, the API will not include the actual location data in the response. Instead, only the meta information such as bounding box, time range, and start and end points is returned.