neorun web api interface specifications rev.1before you use neorun web api, you have to register...

（Control number：）

NeoRun Web API Interface Specifications Rev.1.1 Sheet : 1 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT

Form Rev.0.3

EPSON Sensing System Operations Division

S Planning & Design Department 281 Fujim Fujimi-machi, Suwa-gun, Nagano-ken, 399-0293, Japan

Phone : 81-263-61-1211

TITLE NeoRun Web API Interface Specifications Rev.1.1

PUBLISHED FROM : S Planning & Design Department Total page ：40

Rev. CHANGE DOCUMENT DATE DRAWN CHECK APPRO.

- New Document. (review on 9/9 has been reflected) 2013/9/9 Ito ― ―

- Review on 9/10 has been reflected. 2013/09/11 Ito ― ― 0.1 English translation. 2013/09/13 Ito Fukui Suzuki 0.2 Reduce redundant part of the JSON response.

Review overall. 2014/01/21 Ito Nagahara Suzuki

0.3 Modify according to NeoRun web apps update. 2014/05/07 Ito Nagahara Suzuki

0.4 Add the event parameter to TrainingList and TrainingDetail responses.

2014/06/09 Ito Nagahara Suzuki

0.5 Add the error to the export function. 2014/06/13 Ito Nagahara Suzuki 0.6 Add description for difference in the number of data

between GPS data and graph data. 2014/06/20 Ito Nagahara Suzuki

1.0 Add response sample and description for output time in Export Function.


1.1 Add query parameters and response parameters to TrainingList and TrainingDetail. Add kind of “event” type to the response parameter of TrainingList and TrainingDetail.




Form Rev.0.3

Change Document List

Rev. Sheet Item Description Reason

0.2 13 Structure of JSON

resources Explain Structure of JSON response.

For explain

0.2 All All For reduce redundant part of the JSON response, add

query parameters and change each sample JSON.

Full review

0.3 14 Structure of JSON

resources

Described for the case where the data you have requested

is empty.

For explain

0.3 All All The datetime format changes to Java's SimpleDateFormat

form.

Because decided the rules

where were unclear.

0.3 All All Add etag in response header instead of remove etag in

response body.


where were unclear.

0.3 14 Get training list Append the range of values to the description of the query

parameters.

Because it was not enough.

0.3 20 Get training detail Fixed to description for invalid values. To change values along

with specifications.

0.3 20 Get training detail Delete the parameters of non-correspondence Because it was determined

to be unsupported.

0.3 28 Get GPS data Add “status” parameter to response body. Function addition

0.3 31 Get training report Append the range of values to the description of the query

parameters.


0.3 37 Export Add “time_zone” and “summer_time” to query parameters. Leakage function

0.3 5 Unit Conversion Add about unit conversion. Because decided the rules

where were unclear.

0.3 5 Link to NeoRun

authorization page

Fixed the Link to NeoRun authorization page

0.4 14, 20 Get training list,

Get training detail

Add the event parameter to TrainingList and TrainingDetail

responses.

Function addition

0.5 37 Export Add the error to the Export function when can’t find gps

data.


0.6 28 Get GPS data Add description for the difference in the number of data

between GPS data and graph data.


1.0 37 Export Add response sample and description for output time in

Export Function.


where were unclear.

1.1 14,20 Get training list Get training detail

For getting product name and gps status, add query

parameters and response parameters.

Add “Ski”, “Trail” and “Climbing” to the event type in the

response of TrainingList and TrainingDetail.

Function addition

※Page number is enabled only for the latest revision.



Form Rev.0.3

Table of contents

1. SCOPE OF APPLICATION ......................................................................................................................... 4

2. AUTORIZATION / AUTHENTICATION .................................................................................................... 4

2.1. Getting started with NeoRun Web API ........................................................................................ 4 2.1.1. Registration Information ................................................................................................................................... 4 2.1.2. Send Connection Information ........................................................................................................................... 4

2.2. Authorization .................................................................................................................................. 5 2.2.1. Authorization flow (In case redirection URI is specified) ................................................................................. 5 2.2.2. Link to NeoRun authorization page .................................................................................................................. 5 2.2.3. Redirect to your Application ............................................................................................................................. 5

2.3. Authentication ................................................................................................................................ 6 2.3.1. Authentication of API ........................................................................................................................................ 6 2.3.2. Client Authentication ........................................................................................................................................ 6 2.3.3. Access Token Authentication ............................................................................................................................ 6

2.4. Access token / Refresh token ......................................................................................................... 7 2.4.1. Issue Access token / Refresh token ................................................................................................................... 7 2.4.2. Reissue Access token ...................................................................................................................................... 10

3. WEB API ....................................................................................................................................................13

3.1. Structure of JSON resources .................................................................................................... 13 3.2. Unit Conversion ............................................................................................................................ 13 3.3. TRAINING API............................................................................................................................. 14

3.3.1. Get training list ................................................................................................................................................ 14 3.3.2. Get training detail ............................................................................................................................................ 20 3.3.3. Get GPS data ................................................................................................................................................... 28 3.3.4. Get training report ........................................................................................................................................... 31

3.4. Data ............................................................................................................................................... 37 3.4.1. Export .............................................................................................................................................................. 37

4. COMMON ERROR .....................................................................................................................................41



Form Rev.0.3

1. Scope of application This specification is applied to the web API development of EPSON’s GPS running web services (NeoRun).

2. AUTORIZATION / AUTHENTICATION

2.1. Getting started with NeoRun Web API

Before you use NeoRun Web API, you have to register your service to EPSON OAuth server and get client

authentication information.

2.1.1. Registration Information

item usage example

Service Name This is used to show your service name to users (common in

WW). Please refer to Authorization for more detail. Scan To Cloud

Main URL of

Service

Specify your service URL. It is presented to user on

authorization screen. Please refer to Authorization for more

detail. http://www.epsonconnect.com/

Using Scope Specify the scope that you will access. (Please refer API

Reference to see the scope that you can specify.) user, gps(TBD)

Redirect URI Specify target URI to redirect after authorization procedure.

Please refer to Authorization for more detail. http://....com/auth/completed

2.1.2. Send Connection Information

After registering your service, EPSON OAuth administrator sends following information for both production

and staging environment.

Please refer to Authentication for more detail.

• Client authentication information

• Connected base URL

http://www.epsonconnect.com/http://....com/auth/completed



Form Rev.0.3

2.2. Authorization In order to use API, you require user's authorization and get access token.

You use OAuth 2.0 as authorization protocol.

2.2.1. Authorization flow (In case redirection URI is specified)

When you specified redirect URI at service registration, the flow is as follows;

1. User clicks the link (to "EPSON OAuth authorization page") on your application.

2. User authenticates on EPSON OAuth authorization page.

3. User approves the authorization to access your service. (After approving, NeoRun will redirect to the

URI (that you specified) with authorization code *).

4. You get a user token from authorization code that your application receives.

Please use POST /auth/token.

* Please refer the specification of each OS or framework to see how local application gets authorization

code on OAuth 2.0.

2.2.2. Link to NeoRun authorization page

Link to NeoRun authorization page is as follows.

Base URL + /account/oauth2/authorize/?response_type=code&client_id=Client ID &redirect_uri=Redirect URI&scope=Scope&state=State String

* Staging Server’s Link Stating Server Base URL + /account/oauth2/authorize.html?......... 2.2.3. Redirect to your Application

Following specification is used when redirect to your application.

(State String is the string that you specified at "Link to NeoRun authorization page")

• Normal

Redirect URI + ?code=Authorization Code&state=State String

• Error

Redirect URI + ?error=Error Code&state=State String

subject authentication Method

invalid_scope The specified scope is invalid. Please confirm if the specified data is correct.

server_error EPSON OAuth server internal error.

unsupported_response_type response_type is invalid. Please confirm if "code" is specified

temporarily_unavailable EPSON OAuth server is not available temporarily. Please try again after a while.



Form Rev.0.3

2.3. Authentication The authentication model used to access user data is complying with OAuth2.0.

2.3.1. Authentication of API

• Before using API, authentication is required.

• Available subject is specified for each API. So please use correct authentication method responding to the subject.

Subject Authentication Method

service Client authentication

user Token authentication

2.3.2. Client Authentication

• This authentication method is to set the client authentication information that is published to you in case of requesting API.

• Please add following authentication string in HTTP header when you call request API. o Authentication string: Encoded string by BASE64 of "Client ID + ':' + Client secret"

Authorization: Basic authentication string

2.3.3. Access Token Authentication

• This authentication method is to set the access token that is published to you in case of requesting API.

• Please add following string in HTTP header when you call request API. Authorization: Bearer access token

• Validity period of access token is 1 hour. When the period is expired, please reissue the access token.

• You can get the access token by requesting POST /auth/token.

Reissue Access Token • Please reissue access token by setting refresh token.

o Please refer POST auth/token for more detail.



Form Rev.0.3

2.4. Access token / Refresh token

2.4.1. Issue Access token / Refresh token

Function

Issue Access Token/Refresh Token from authorization code.

Corresponding subject

※about subject, please refer to Authentication.

service (public)

Request

Request

POST /oauth2/auth/token HTTP/1.1

Query parameter

none.

Header

※M:Mandatory, O:Optional

header M/O description

Host M "api.sensing.epsonconnect.com".

Accept M "application/json;charset=utf-8".

Content-Length M Specify size of Request Body.

Authorization M Specify by using Basic authentication format. specify Client

ID into username and Client Secret into password.

Content-Type M "application/x-www-form-urlencoded".



Form Rev.0.3

Request body

grant_type=value&authorization_code=value&redirect_uri=value

header M/O Type description

grant_type M string Grant Type

specify "authorization_code".

authorization_code M string Authorization Code

redirect_uri M string

Redicrect URI

specify the redirect URI specified when service is registred. when

redirect URI is not set or use the screen that is provided from

Epson Sensing Service Platform, specify "oob".

Response

Normal response

HTTP status

200

{ "access_token": "8rVE8yf75mTrE8OD0wThwhVw53mEPEeWkc9M5laua3bBM1y7wnVDXFi762H6im74",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "CGy751kgw89d4RGEWUB5AWrD851ocuA6ASAK4G7z2x8hiNu8f1EGTDv5OaZ31a97"

"subject_id": "dff5c6a060aa11e3949a0800200c9a66"

"subject_type": "temporary_password" }

property Type description

access_token string Access Token

token_type string Token Type

"Bearer" will be returned. expires_in number Valid Period refresh_token string Refresh Token subject_id string User ID

subject_type string Subject Type



Form Rev.0.3

Error response

※return according as OAuth2.0 specification.

{

"error" : "invalid_request"

}

HTTP Status code description

400 invalid_request Specification of parameter is not correct. 400 invalid_grant Authorization code is not correct. 401 invalid_client Failure is occurred in client authentication. 500 server_error Unexpected error is occurred. 503 temporarily_unavailable NeoRun is stopping temporarily.



Form Rev.0.3

2.4.2. Reissue Access token

Function

Issue Access Token by using Refresh Token.



service (public)

Request

Request

POST /oauth2/auth/token HTTP/1.1

Query parameter

none.

Header



Host M "api.sensing.epsonconnect.com".

Accept M "application/json;charset=utf-8".

Content-Length M specify size of Request Body.

Authorization M specify by using Basic authentication format. specify Client

ID into username and Client Secret into password.

Content-Type M "application/x-www-form-urlencoded".



Form Rev.0.3

Request body

grant_type=value&refresh_token=value

header M/O type description

grant_type M string Grant Type

specify "refresh_token"

refresh_token M string Refresh Token

Response

Normal response

HTTP status

200

{

"access_token": "8rVE8yf75mTrE8OD0wThwhVw53mEPEeWkc9M5laua3bBM1y7wnVDXFi762H6im74",

"token_type": "Bearer",

"expires_in": 3600

"subject_id": "dff5c6a060aa11e3949a0800200c9a66"

"subject_type": "temporary_password"

}

property type description

access_token string Access Token

token_type string Token Type

"Bearer" will be returned. expires_in number Valid Period subject_id string Subject ID

subject_type string Subject Type



Form Rev.0.3

Error response

※return according as OAuth2.0 specification.

{

"error" : "invalid_request"

}

HTTP Status code description

400 invalid_request Specification of parameter is not correct. 400 invalid_grant Refresh token is not invalid. 401 invalid_client Failure is occurred in client authentication. 500 server_error Unexpected error is occurred. 503 temporarily_unavailable NeoRun is stopping temporarily.



Form Rev.0.3

3. WEB API

3.1. Structure of JSON resources The right side of the following figure shows structure of JSON resources. If the response data you get at your

request is empty, The JSON resources will be structured as the left side of the following figure. Please refer

each API reference to see more detail.

3.2. Unit Conversion The NeoRun DB has data with the metric system of units. When you request any data with the imperial

system of units, the API use the following conversion table. About rounding, please refer to each API’s

Response section.

conversion Metric Imperial

meter to mile 1 [meter] 1 / 1609.344 [mile]

meter to feet 1 [meter] 1 / 0.3048 [feet]

centimeter to inch 1 [centimeter] 1 / 2.54 [inch]



Form Rev.0.3

3.3. TRAINING API

3.3.1. Get training list

Function

Get training list.



user

Request

Request

GET /1/gps/users/{user_id}/trainings/ HTTP/1.1


parameter M/O description

user_id M User ID.

Query parameter



start_date O

The training's start date.

About date format see “datetime_format” in this table.

The default date format is “yyyy-MM-dd”.

※default value is one month ago from end_date.

※the range is “2012-01-01” to “2042-12-31”.

start_time O

The training’s start time.

The time format is “HH:mm:ss” (24 hour format).

※default value is “00:00:00”.

end_date O The training's end date.

About date format see “datetime_format” in this table.



Form Rev.0.3

The default date format is “yyyy-MM-dd”.

※default value is current date.

※the range is “2012-01-01” to “2042-12-31”.

end_time O

The training’s end time.

The time format is “HH:mm:ss” (24 hour format).

※default value is “23:59:59”.

limit O

Pagination - number of records to retrieve.

※default value 100

※the range is 1 to 100.

offset O

Pagination - first record to retrieve.

※default value 0


order O

Sort direction. The sort target is the training start datetime.

“ASC” : ascending

“DESC” : descending

※default value “DESC”

datetime_format O

Specify date format from following numbers.

The setting is applied to both input and output.

1 : “ yyyy-MM-dd hh:mm:ss ”

2 : “dd-MM-yyyy hh:mm:ss”

3 : “MM-dd-yyyy hh:mm:ss”

※default value 1.

time_zone O

Specify difference time from UTC [minute].

The output will be in consideration of the time_zone.

※default value 0.

※the range is -720 to 840.

summer_time O

Specify daylight-saving time [minute].

The output will be in consideration of the summer_time.

※default value 0.


unit O

Specify unit system from following numbers.

1 : Metric

2 : Imperial

※default value 1.

prod_flg O

Specify the flag of if response includes prod_name or not.

0 : not include.

1 : include.



Form Rev.0.3

Header



Host M go-wellness.epson.com

Accept M application/json;charset=utf-8

Authorization M Add access token according to the AUTORIZATION / AUTHENTICATION.

Content-Length M Specify the size of request body.

Request body

None.

Response

Header

header description

etag created etag.

Normal response

HTTP status

200

｛

"list_info" : {

"uom" : {

"begin_time_stamp" : "yyyy-MM-dd HH:mm:ss",

※default value 0.

gps_flg O

Specify the flag of if response includes gps_status or not.

0 : not include.

1 : include.

※default value 0.



Form Rev.0.3

"duration" : "sec",

"distance" : "km",

"pace" : "sec/km",

"stride" : "cm",

"average_hr" : "bpm",

"max_hr" : "bpm",

"unit" : "1”

},

"total" : "7",

"start_date" : "2013-09-01",

"start_date" : "00:00:00",

"end_date " : "2013-09-10",

"start_date" : "14:25:36",

"limit" : "100",

"offset" : "0",

"order" : "DESC",

"datetime_format" : "1",

"time_zone" : "540",

"summer_time" : "60",

"unit" : "1",

“prod_flg” : “1”,

“gps_flg” : “1”

},

"list_data" : {

"begin_time_stamp" : ["2013-09-01 00:00:00", "2013-09-02 00:00:00", … ,"2013-09-06

00:00:00", "2013-09-07 00:00:00"],

"duration" : ["3600", "3600", … , "3600", "3600"],

"distance" : ["8.0", "8.0", … , "8.0", "8.0"],

"pace" : ["450", "450", … ,"450", "450"],

"stride" : [],

"average_hr" : ["140", "135", … , "130", "125"],

"max_hr" : ["160", "150", … , "145", "140"]

"id" : ["23", "24", … , "28", "29"]

"event" : ["Run", "Run", … , "Walk", "Bike"],

"type" : ["Training", "Training", … , "Training", "Training"],

"title" : ["Hard Work", "Jog", … , "Jog", "Jog"],

"ranking" : ["27", "", … , "", ""],

“prod_name” : [“SS-500”,”SS-500”, … ,“SF-710”,”SF-710”],

“gps_status” : [“1”,”1”, … ,”3”,”1”]



Form Rev.0.3

}

}


list_info

uom

begin_time_stamp String Date format depends on query parameter “datetime_format”.

duration String Unit of duration. Round down.

[sec]

distance String

Unit of distance. Round to three decimal places.

metric : [km]

imperial : [mile]

pace String

Unit of average pace. Round down.

metric : [sec] (※[sec / km])

imperial :[sec] (※ [sec / mile])

average_hr String Unit of average heart rate. Round down.

[bpm]

max_hr String Unit of average heart rate. Round down.

[bpm]

total String Total number of specified time period that does not consider

the offset and limit.

start_date String Query parameter entered by user.

end_date String Query parameter entered by user.

limit String Query parameter entered by user.

offset String Query parameter entered by user.

datetime_format String Query parameter entered by user.

time_zone String Query parameter entered by user.

summer_time String Query parameter entered by user.

unit String Query parameter entered by user.

prod_flg String Query parameter entered by user.

※This parameter returns only when the “prod_flg” = 1.

gps_flg String Query parameter entered by user.

※This parameter returns only when the “gps_flg” = 1.

list_data

begin_time_stamp Array Start date of each training. Each elements will consider time

zone and summer_time that user enters.

duration Array Duration time at each training.

distance Array Distance at each training.

pace Array Average pace at each training.

average_hr Array Average heart rate at each training.



Form Rev.0.3

max_hr Array Maximum heart rate at each training.

id Array Training id.

event Array

Training event. “Run”, “Walk”, “Bike”, ”Ski”, “Trail”, “Climbing”

※If user has inputted “” or “etc1” or “etc2” to this parameter

then return “Run”.

type Array

Training type.

“Training”, “Race”, “Race – 10km”, Race – Half Marathon”,

“Race – Marathon”, “Other”

title Array Title.

ranking Array Ranking.

prod_name Array Product names which were used for these trainings.


gps_status Array

Present the status of the GPS data. This value equals the

value of “status” in “gps_info”.

※Please refer to Response section of Get GPS data.


※If you have not input any, the response param would be “”.

Error response

※about common error, please refer to Common error.



Form Rev.0.3

3.3.2. Get training detail

Function

Get training detail.



user

Request

Request

GET /1/gps/users/{user_id}/trainings/{id}/ HTTP/1.1



user_id M User ID

id M Training ID

Query parameter



datetime_format O

Specify date time format from following numbers.

The setting is applied to output.

1 : “yyyy-MM-dd HH:mm:ss”

2 : “dd-MM-yyyy HH:mm:ss”

3 : “MM-dd-yyyy HH:mm:ss”

※defalut value 1.

time_zone O


The output is in consideration of the time_zone.

※default value 0.


summer_time O Specify daylight-saving time [minute].



Form Rev.0.3

The output is in consideration of the summer_time.

※default value 0.


unit O


1 : Metric

2 : Imperial

※default value 1.

prod_flg O

Specify the flag of if response includes prod_name or not.

0 : not include.

1 : include.

※default value 0.

status_flg O

Specify the flag of if response includes gps_status or not.

0 : not include.

1 : include.

※default value 0.

Header







Request body

None.

Response

Header

header description

etag created etag.



Form Rev.0.3

Normal response

HTTP status

200

｛

"summery_info" : {

"uom" : {

"begin_time_stamp" : "yyyy-MM-dd HH:mm:ss",

"duration" : "sec",

"distance" : "km",

"energy" : "kcal",

"pace" : "sec/km",

"pitch" : "spm",

"stride" : "cm",

"hr" : "bpm"

},

"datetime_format" : "1",



"unit" : "1",

"prod_flg" : "1",

"gps_flg" : "1"

},

"lap_info" : {

"uom" : {

"lap_duration" : "sec",

"sum_duration" : "sec",

"lap_distance" : "km",

"sum_distance" : "km",

"lap_energy" : "kcal",

"pace" : "sec/km",

"pitch" : "spm",

"average_hr" : "bpm",

"max_hr" : "bpm",

"stride" : "cm"

},

},



Form Rev.0.3

"graph_info" : {

"uom" : {

"time" : "sec",

"alt" : "m",

"speed" : "km/h",

"pace" : "sec/km",

"pitch" : "spm",

"hr" : "bpm",

"distance" : "m",

"slope" : "m",

"stride" : "cm"

},

},

"summary_data" : {

"begin_time_stamp" : ["2013-09-01 10:25:00"],

"duration" : ["3600"],

"distance" : ["8.0"],

"energy" : ["200"],

"pace" : ["450"],

"pitch" : null,

"hr" : ["140"],

"stride" : null,

"id" : ["23"],

“event” : ["Run"],

"type" : ["Training"],

"title" : ["no title"],

"memo" : ["Strong head wind, sunshine was hard."],

“prod_name” : [“SF-710”],

“gps_status” : [“1”]

},

"lap_data" : {

"lap_duration" : ["450", "450", … , "450"],

"sum_duration" : ["450", "900", … , "3600"],

"lap_distance" : ["1.0", "1.0", … , "1.0"],

"sum_distance" : ["1.0", "2.0", … , "8.0"],

"lap_energy" : ["25", "25", … , "25"],

"pace" : ["450", "450", … , "450"],

"pitch" : null,

"average_hr" : ["130", "130"… , "130"],



Form Rev.0.3

"max_hr" : ["140, "135", … "145"],

"stride" : null,

"locale_index" : ["0", "-1", … "-1"],

},

"graph_data" : {

"time" : ["0", "1", …, "3600"],

"alt" : ["632", "642", …, "627"],

"speed" : ["8.0", "8.0", …, "8.0"],

"pace" : ["450", "450", … , "450"],

"pitch" : null,

"hr" : ["80", "85", … , "140"],

"distance" : ["9", "8", … , "9"],

"slope" : ["0", "1", … , "-1"],

"stride" : null

}

}


summary_info

uom

begin_time_stamp String The format depends on query parameter "datetime_format”.

duration String Unit of duration. Round down.

[sec]

distance String


metric : [km]

imperial : [mile]

energy String Unit of calories. Round down.

[kcal]

pace String



imperial : [sec] (※[sec / mile])

pitch String Unit of average pitch. Round down.

[spm]


[bpm]

stride String Unit of average stride. Round down.

[bpm]

date_format String Query parameter entered by user.




Form Rev.0.3



prod_flg String Query parameter entered by user.


gps_flg String Query parameter entered by user.


lap_info uom

lap_duration String Unit of duration, round down.

[sec]

sum_duration String Unit of total time for all laps. Round down.

[sec]

lap_distance String


metric : [km]

imperial : [mile]

sum_distance String

Unit of total distance. Round to three decimal places.

metric : [km]

imperial : [mile]

lap_energy String Unit of calories. Round down.

[kcal]

average_pace String




average_pitch String Unit of average pitch. Round down.

[spm]


[bpm]

max_hr String unit of maximum heart rate. Round down.

[bpm]

average_stride String

unit of average stride. Round down.

metric : [cm]

imperial : [inch]

graph_info uom

time String Unit of elapsed time from start. Round down.

[sec]

alt String

Unit of altitude. Round down.

metric : [m]

imperial : [feet]

speed String

Unit of speed. Round to three decimal places.

metric : [km / h]

imperial : [mile / h]

pace String Unit of pace. Round down.



Form Rev.0.3



pitch String unit of pitch. Round down.

[spm]

hr String unit of heart rate. Round down.

[bpm]

distance String

Unit of distance from the last point. Round to three decimal

places.

metric : [km]

imperial : [mile]

slope String

Unit of slope change from the last point. Round down.

metric : [m]

imperial : [feet]

stride String

Unit of stride. Round down.

metric : [cm]

imperial : [inch]

summary_data

begin_time_stamp Array Start date time of the training. The member will consider time

zone and summer_time that user enters.

duration Array Duration time at the training.

distance Array Distance at the training.

energy Array Average pace at the training.

pace Array Average pace at the training.

pitch Array Average pitch at the training.

average_hr Array Average heart rate at the training.

stride Array Average stride at the training.

id Array Training id.

event Array

Training event. “Run”, “Walk”, “Bike”, “Ski”, “Trail”, “Climbing”

※If user hast inputted “” or “etc1” or “etc2” to this parameter

then return “Run”.

type Array

Training type.

“Training”, “Race”, “Race – 10km”, Race – Half Marathon”,

“Race – Marathon”, “Other”

title Array Title.

memo Array Memorandum.

prod_name Array

Product name which was used for this training.


※If this training does not have product name, will return “”.

gps_status Array Present the status of the GPS data. This value equals the

value of “status” in “gps_info”.



Form Rev.0.3

※Please refer to Response section of Get GPS data.


lap_data

lap_duration Array Duration time at each lap.

sum_duration Array Total time for all laps.

lap_distance Array Distance at each lap.

sum_distance Array Total distance for all laps.

lap_energy Array Calories at each lap.

average_pace Array Average pace at each lap.

average_pitch Array Average pitch at each lap.

average_hr Array Average heart rate at each lap.

max_hr Array Maximum heart rate at each lap.

average_stride Array Average stride at each lap.

locale_index Array

Index number of the gps_data elements.

※Numbers start at 0.

※The range is 0 to 999999.

※If it has not been measured, put ‘1000000’.

graph_data

time Array Elapsed time from start.

alt Array

Altitude at each point.

The range is -500 to 9999.

※If invalid value appears, put “-1000”.

speed Array Speed at each point.

pace Array Pace at each point.

※If speed value is invalid or ‘0.0’, put “” (blank).

pitch Array Pitch at each point.

hr Array Heart Rate at each point.

distance Array Distance from the last point.

slope Array Slope change from the last point.

stride Array Stride at each point..

※If you have not input any, the response param would be “”.

Error response


HTTP status code description

404 training_not_found Specified training does not exist. Check trainingID you request.



Form Rev.0.3

3.3.3. Get GPS data

Function

Get GPS data.


※about subject, please refer to Authentication. user

Request

Request

GET /1/gps/users/{user_id}/trainings/{id}/gps_data HTTP/1.1



user_id M User ID

id M Training ID

Query parameter



unit O


1 : Metric

2 : Imperial

※default value 1.

Header









Form Rev.0.3

Request body

None. Response

Header

header description

etag created etag.

Normal response

HTTP status

200

｛

"gps_info" : {

"uom" : {

"time" : "sec",

"lat" : "dd",

"lon" : "dd",

"alt" : "m",

"speed" : "km/h"

},

“status” ; “1”,

"id" : "23",

"unit" : "1"

},

"gps_data" : {

"time" : ["0", "1", …, "3600"],

"lat" : ["36.23456", "36.345678", …, "36.456789"],

"lon" : [ "139.123456", "139.23456", … , "139.345678"],

"alt" : ["632", "642", …, "627"],

"speed" : ["8.0", "8.0", …, "8.0"],

}

}



Form Rev.0.3


gps_info

uom

time String Unit of elapsed time from start. Round down

[sec]

lat String Unit of latitude. Raw value in NeoRun DB.

[dd]

lon String Unit of longitude. Raw value in NeoRun DB.

[dd]

alt String

Unit of altitude. Round down.

metric : [m]

imperial : [feet]

speed String

Unit of speed. Round to three decimal places.

metric : [km / h]


status String

Present the status of GPS data by following numbers.

“1” : GPS data is exist.

“2” : Specified data has not fully uploaded yet.

“3” : .Specified training does not have GPS data.

id String Training id.


gps_data

time Array Elapsed time from start.

lat Array Latitude at each point.

lon Array Longitude at each point.

alt Array Altitude at each point.

speed Array Speed at each point.

※If you have not input any, the response param would be “”. ※The following case is also assumed:

・A number of GPS data is greater than a number of training detail.

・A number of GPS data is less than a number of training detail.

It depends on a model of GPS Watches. So if the data is registered by old model (SS series), there are some

situation that the HR data corresponding to GPS data is not included in training detail.

Error response






Form Rev.0.3

3.3.4. Get training report

Function

Get monthly training statistics. Corresponding subject


user Request

Request

GET /1/gps/users/{user_id}/report HTTP/1.1



user_id M User ID

Query parameter



start_month O

The training's start month.

About date format see “date_format” in this section.

The default date format is “yyyy-MM”.

※default value is 11 months ago from end_month.

※the range is “2012-01” to “2042-12”.

end_month O

The training's end month.

About date format see “date_format” in this section.

The default date format is “yyyy-MM”.

※default value is this month.

※the range is “2012-01” to “2042-12”.

limit O

Pagination - number of records to retrieve.

※default value 12


date_format O Specify date format from following numbers.

Settings are applied to both input and output.



Form Rev.0.3

1 : “yyyy-MM”

2 : “MM-yyyy”

※defalut value 1.

time_zone O



※default value 0.


summer_time O

Specify daylight-saving time [minute].


※default value 0.


unit O


1 : Metric

2 : Imperial

※default value 1.

Header







Request body

None.

Response

Header

header description

etag created etag.



Form Rev.0.3

Normal response

HTTP status

200

｛

"monthly_info" : {

"uom" : {



"average_pace" : "sec/km",

"average_speed" : "km/h",

"average_distance" : "km",

"sum_energy" : "kcal",

"month" : "yyyy-MM"

},

"total" : "2",

"start_month" : "2013-09",

"end_month" : "2013-10",

"limit" : "",

"date_format" : "1",



"unit" : "1"

},

"report_info" : {

"uom" : {



"average_pace" : "sec/km",

"average_speed" : "km/h",

"average_distance" : "km",

"sum_energy" : "kcal"

"total" : "15"

},

"monthly_data" : {

"sum_distance" : ["56.0, 64.0"],

"sum_duration" : ["25200", "28800"],



Form Rev.0.3

"average_pace" : ["450", "450"],

"average_speed" : ["8.0", "8.0"],

"average_distance" : ["8.0", "8.0"],

"sum_energy" : ["200", "225"],

"total" : ["7", "8"],

"month" : ["2013-09", "2013-10"]

},

"report_data" : {

sum_distance : ["120.0"],

sum_duration : ["54000"],

average_pace : ["450"],

average_speed : ["8.0"],

average_distance : ["8.0"],

sum_energy : ["425"],

total : ["15"]

}

}


monthly_info

uom

sum_distance String


metric : [km]

imperial : [mile]

sum_duration String Unit of total duration. Round down.

[sec]

average_pace String




average_speed String

Unit of average speed. Round to three decimal places.

metric : [km / h]


average_distance String

Unit of average distance. Round to three decimal places.

metric : [km]

imperial : [mile]

sum_energy String Unit of total calories. Round down.

[kcal]

month String Date format depends on query parameter "date_format".

total String Total number of months in the period that user entered.

start_month String Query parameter entered by user.



Form Rev.0.3

end_month String Query parameter entered by user.

limit String Query parameter entered by user.

date_format String Query parameter entered by user.




report_info uom

sum_distance String


metric : [km]

imperial : [mile]

sum_duration String Unit of total duration. Round down.

[sec]

average_pace String




average_speed String

Unit of average speed. Round to three decimal places.

metric : [km / h]


average_distance String

Unit of average distance. Round to three decimal places.

metric : [km]

imperial : [mile]

sum_energy String Unit of total calories. Round down.

[kcal]

total String Total number of trainings in the whole period.

monthly_data

sum_distance Array Sum of distance in each month.

sum_duration Array Sum of duration time in each month.

average_pace Array Average pace at each month.

average_speed Array Average speed at each month.

average_distance Array Average distance at each month.

sum_energy Array Sum of calories at each month.

total Array Total number of trainings in the month.

month Array Statistics month.

report_data

sum_distance Array Total distance.

sum_duration Array Total duration time.

average_pace Array Average pace.

average_speed Array Average speed.

average_distance Array Average distance.

sum_energy Array Total calories.

total Array Total number of trainings.



Form Rev.0.3

Error response




Form Rev.0.3

3.4. Data

3.4.1. Export

Function

Export training data.



user

Request

Request

GET /1/gps/users/{user_id}/export/{id}/ HTTP/1.1


user_id M User ID

id M Training ID

Query parameter



time_zone O



※default value 0. （According to specifications of GPX, the output of the time is usually UTC time.） ※the range is -720 to 840.

summer_time O

Specify daylight-savings time [minute].


※default value 0. （According to specifications of GPX, the output of the time is usually UTC time.） ※the range is 0 to 120.



Form Rev.0.3

Header ※M:Mandatory, O:Optional



Accept M application/xml,text/plain;charset=utf-8



Request body

None.

Response

Header

header description

etag created etag.

Normal response

HTTP status

200

※About gpx format, please refer to Official GPX web site. (e.g.) time_zone = 0, summer_time=0

※The time representation conforms to ISO 8601 specification.

Tokyo Marathon

8 degree, cloudy, a little windy

220

2014-02-24T00:10:54Z

http://www.topografix.com/gpx.asphttps://go-wellness.epson.com/neo-run/



Form Rev.0.3

220

2014-02-24T00:11:49Z

…

(e.g.)time_zone = 540, summer_time=0 (Outside of the specifications of GPX)


Tokyo Marathon


220

2014-02-24T09:10:54+09:00

220

2014-02-24T09:11:49+09:00

…

https://go-wellness.epson.com/neo-run/



Form Rev.0.3

(e.g.)time_zone = 0, summer_time=60 (Outside of the specifications of GPX)


Tokyo Marathon


220

2014-02-24T01:10:54+01:00

220

2014-02-24T01:11:49+01:00

…

Error response




412 gpsdata_not_found Specified training does not have GPS data. Check state parameter in response of Get GPS data function.

https://go-wellness.epson.com/neo-run/



Form Rev.0.3

4. Common Error

The followings are errors that may occur in the API common.

HTTP

status code description

400 validation_error Validation error. Check parameter format you request.

401 client_authentication_error Client authentication is failed. Check your information of client

authentication.

401 access_token_verification_error Invalid access token. Please reissue an access token.

※Expiration date of access token is 1 hour.

403 forbidden You do not have permission to access resources. Check resource ID.

403 rate_limit_exceeded Not available due to excessive access. Try again in later.

405 method_not_allowed Invalid HTTP method.

406 not_acceptable Your specified accept header was invalid. Check

“application/json;charset=utf-8” has been specified.

415 unsupported_media_type Your specified content-type header was invalid. Check

“application/json;charset=utf-8” has been specified.

500 internal_server_error Internal server error occurred. If the error persists even after retry,

there could be interference with NeoRun.

503 system_maintenance NeoRun is currently undergoing maintenance. Wait until maintenance

ends before trying again.

1. Scope of application2. AUTORIZATION / AUTHENTICATION2.1. Getting started with NeoRun Web API2.1.1. Registration Information2.1.2. Send Connection Information

2.2. Authorization2.2.1. Authorization flow (In case redirection URI is specified)2.2.2. Link to NeoRun authorization page2.2.3. Redirect to your Application

2.3. Authentication2.3.1. Authentication of API2.3.2. Client Authentication2.3.3. Access Token Authentication

2.4. Access token / Refresh token2.4.1. Issue Access token / Refresh token2.4.2. Reissue Access token

3. WEB API3.1. Structure of JSON　resources3.2. Unit Conversion3.3. TRAINING API3.3.1. Get training list3.3.2. Get training detail3.3.3. Get GPS data3.3.4. Get training report

3.4. Data 3.4.1. Export

4. Common Error

neorun web api interface specifications rev.1before you use neorun web api, you have to register...

Documents