General

You must have a valid access token before being able to use the API, see authentication on how to obtain an access token.

The API is only available using https. The base url to the API is:

https://api.moves-app.com/api/1.1

The API calls described below are relative to the base url.

Authenticating requests

Each API call must include a valid access token given either in the HTTP Authorization header or as a query parameter in the request url.

 GET /api/1.1/user/summary/daily/20130401
 Authorization: Bearer <access_token>

 GET /api/1.1/user/summary/daily/20130401?access_token=<access_token>

If the access token is not valid, HTTP status code 401 Unauthorized is returned.

Time zones

Currently the exact timespan used to query data for a day depends on user’s current time zone, which is provided in the profile API.
We are working on improving the time zone support in the future, so that the current time zone will not affect history.
The timestamps in API responses are in users local time, with time zone designator included in the timestamp.

Rate limiting

An unpublished app can make at most 2000 requests per hour and 60 requests per minute. For apps published in Connected Apps, the limits are 4000 requests per hour and 120 requests per minute. The quotas reset at the top of each hour and minute. Each response includes the headers X-RateLimit-HourLimit, X-RateLimit-HourRemaining, X-RateLimit-MinuteLimit and X-RateLimit-MinuteRemaining with the current values. If the rate limiting is activated, the 429 Too Many Requests response code is returned. If you need a higher limit, please contact us at api@moves-app.com

Date ranges

The from/to date range in API calls must be between firstDate in user profile and the current day. When requesting data for a specific week or month, the week/month must be between week/month of first date in user profile and current week/month.

Data syncing

In ideal conditions the API should provide at most couple of hours old user data. User data is uploaded to our servers whenever user opens the app in phone and periodically every couple of hours.
The data updates may be irregular if user has bad internet connection or is using the Moves battery saving mode.

ETag

All API calls return an ETag header in the response with some value. You can provide If-None-Match header with a previously saved ETag value in the API call and if the ETag values still match, server will respond with 304 Not Modified response code and empty body. If the ETag values do not match, full response is returned instead. See http://en.wikipedia.org/wiki/HTTP_ETag for more details.

Last-Modified

All API calls, except profile, return a Last-Modified header in the response with some timestamp in RFC 1123 format. You can provide If-Modified-Since header in the API call in same format and if the data for the date range has not been updated since then, server will respond with 304 Not Modified response code and an empty body.
Server will check both If-None-Match and If-Modified-Since headers if both are included in the request, and only respond with 304 Not Modified if they both agree. Full response is always returned if neither one of the headers is included.

Gzip

You can set HTTP request header Accept-Encoding: gzip to receive compressed responses.

API v1 (deprecated)

The /api/v1/ endpoints have been deprecated and will be removed after 1H 2014.

Documentation for V1 endpoints:

Profiles v1
Summaries v1
Activities v1
Places v1
Storylines v1

API v1 -> 1.1 changes and migration guide

  • the API base url has changed to https://api.moves-app.com/api/1.1
  • the activity names have changed and activities have an optional group field in both summaries and storylines
    • the API v1 activities can be mapped to an activity group (which also includes stationary/indoor walking, cycling and running variants) or exact activity name in API 1.1 as follows:
    • activity: wlk -> group: walking or activity: walking
    • activity: cyc -> group: cycling or activity: cycling
    • activity: run -> group: running or activity: running
    • activity: trp -> group: transport
  • new activities have been added and there is now an API endpoint for querying currently supported activities, see Activity list API. For human readable version, see table of activities
    • note that currently Moves for Android only supports activities walking, cycling, running and transport
  • the ISO 8601 timestamps in storylines now use users current local time instead of UTC. The time zone designator is included in the timestamp.
    • if you are using the segment startTime as a unique ID, you should probably convert the timestamp to UTC or unix time first
  • the allowed date ranges have been expanded from 7 days to 31 days for storyline queries without track points, and from 1 to 7 days for storyline queries with track points
  • the storyline API now also returns the activity summaries for each day
  • the summaries now include all activity types, including transport
  • there is a new manual flag to indicate whether an activity was manually added by user. Note that only in-place activities can currently be added manually. Geo-activities are currently never manually added, even if corrected by user to a different activity
  • the startTime and endTime of activities are now optional and may not be always available (for manually entered activities)
  • there is a new lastUpdate timestamp in summaries and storylines which tells when data was last updated for a day or storyline segment
  • support for Last-Modified and If-Modified-Since HTTP headers in summary and storyline API calls
  • support for updatedSince query parameter in summary and storyline API calls
  • profile includes users localization settings, if available
  • new notifications API for receiving callbacks when users storyline updates, see Notifications API
  • places now include Foursquare category ids, if available. Available only for recently added 4sq places with iOS.
  • users current time zone can be overridden in the request for summary and storyline API calls, affecting the time period from which data is returned.