Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
(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.
2014/06/26 Ito Nagahara Suzuki
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.
2014/10/10 Ito Nagahara Suzuki
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 2 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
Because decided the rules
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.
Because it was not enough.
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.
Because it was not enough.
0.6 28 Get GPS data Add description for the difference in the number of data
between GPS data and graph data.
Because it was not enough.
1.0 37 Export Add response sample and description for output time in
Export Function.
Because decided the rules
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 3 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 4 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 5 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 6 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 7 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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".
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 8 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 9 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 10 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
2.4.2. Reissue Access token
Function
Issue Access Token by using Refresh Token.
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".
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 11 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 12 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 13 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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]
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 14 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
3.3. TRAINING API
3.3.1. Get training list
Function
Get training list.
Corresponding subject
※about subject, please refer to Authentication.
user
Request
Request
GET /1/gps/users/{user_id}/trainings/ HTTP/1.1
※M:Mandatory, O:Optional
parameter M/O description
user_id M User ID.
Query parameter
※M:Mandatory, O:Optional
header M/O description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 15 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
※the range is 0 to 3000.
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.
※the range is 0 to 120.
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 16 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
Header
※M:Mandatory, O:Optional
header M/O description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 17 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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”]
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 18 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
}
}
property type description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 19 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
※This parameter returns only when the “prod_flg” = 1.
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.
※This parameter returns only when the “gps_flg” = 1.
※If you have not input any, the response param would be “”.
Error response
※about common error, please refer to Common error.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 20 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
3.3.2. Get training detail
Function
Get training detail.
Corresponding subject
※about subject, please refer to Authentication.
user
Request
Request
GET /1/gps/users/{user_id}/trainings/{id}/ HTTP/1.1
※M:Mandatory, O:Optional
parameter M/O description
user_id M User ID
id M Training ID
Query parameter
※M:Mandatory, O:Optional
parameter M/O description
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
Specify difference time from UTC [minute].
The output is in consideration of the time_zone.
※default value 0.
※the range is -720 to 840.
summer_time O Specify daylight-saving time [minute].
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 21 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
The output is in consideration of the summer_time.
※default value 0.
※the range is 0 to 120.
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.
※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
※M:Mandatory, O:Optional
parameter M/O description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 22 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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",
"time_zone" : "540",
"summer_time" : "60",
"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"
},
},
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 23 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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"],
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 24 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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
}
}
property type description
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
Unit of distance. Round to three decimal places.
metric : [km]
imperial : [mile]
energy String Unit of calories. Round down.
[kcal]
pace String
Unit of average pace. Round down.
metric : [sec] (※[sec / km])
imperial : [sec] (※[sec / mile])
pitch String Unit of average pitch. Round down.
[spm]
average_hr String Unit of average heart rate. Round down.
[bpm]
stride String Unit of average stride. Round down.
[bpm]
date_format String Query parameter entered by user.
time_zone String Query parameter entered by user.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 25 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
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.
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
Unit of distance. Round to three decimal places.
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
Unit of average pace. Round down.
metric : [sec] (※[sec / km])
imperial : [sec] (※[sec / mile])
average_pitch String Unit of average pitch. Round down.
[spm]
average_hr String Unit of average heart rate. Round down.
[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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 26 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
metric : [sec] (※[sec / km])
imperial : [sec] (※[sec / mile])
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.
※This parameter returns only when the “prod_flg” = 1.
※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”.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 27 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
※Please refer to Response section of Get GPS data.
※This parameter returns only when the “gps_flg” = 1.
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
※about common error, please refer to Common error.
HTTP status code description
404 training_not_found Specified training does not exist. Check trainingID you request.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 28 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
3.3.3. Get GPS data
Function
Get GPS data.
Corresponding subject
※about subject, please refer to Authentication. user
Request
Request
GET /1/gps/users/{user_id}/trainings/{id}/gps_data HTTP/1.1
※M:Mandatory, O:Optional
parameter M/O description
user_id M User ID
id M Training ID
Query parameter
※M:Mandatory, O:Optional
parameter M/O description
unit O
Specify unit system from following numbers.
1 : Metric
2 : Imperial
※default value 1.
Header
※M:Mandatory, O:Optional
parameter M/O description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 29 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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"],
}
}
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 30 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
property type description
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]
imperial : [mile / 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.
unit String Query parameter entered by user.
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
※about common error, please refer to Common error.
HTTP status code description
404 training_not_found Specified training does not exist. Check trainingID you request.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 31 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
3.3.4. Get training report
Function
Get monthly training statistics. Corresponding subject
※about subject, please refer to Authentication.
user Request
Request
GET /1/gps/users/{user_id}/report HTTP/1.1
※M:Mandatory, O:Optional
parameter M/O description
user_id M User ID
Query parameter
※M:Mandatory, O:Optional
header M/O description
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
※the range is 1 to 24.
date_format O Specify date format from following numbers.
Settings are applied to both input and output.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 32 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
1 : “yyyy-MM”
2 : “MM-yyyy”
※defalut value 1.
time_zone O
Specify difference time from UTC [minute].
The output is 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 is in consideration of the summer_time.
※default value 0.
※the range is 0 to 120.
unit O
Specify unit system from following numbers.
1 : Metric
2 : Imperial
※default value 1.
Header
※M:Mandatory, O:Optional
header M/O description
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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 33 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
Normal response
HTTP status
200
{
"monthly_info" : {
"uom" : {
"sum_distance" : "km",
"sum_duration" : "sec",
"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",
"time_zone" : "540",
"summer_time" : "60",
"unit" : "1"
},
"report_info" : {
"uom" : {
"sum_distance" : "km",
"sum_duration" : "sec",
"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"],
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 34 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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"]
}
}
property type description
monthly_info
uom
sum_distance String
Unit of total distance. Round to three decimal places.
metric : [km]
imperial : [mile]
sum_duration String Unit of total duration. Round down.
[sec]
average_pace String
Unit of average pace. Round down.
metric : [sec] (※[sec / km])
imperial : [sec] (※[sec / mile])
average_speed String
Unit of average speed. Round to three decimal places.
metric : [km / h]
imperial : [mile / 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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 35 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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.
time_zone String Query parameter entered by user.
summer_time String Query parameter entered by user.
unit String Query parameter entered by user.
report_info uom
sum_distance String
Unit of total distance. Round to three decimal places.
metric : [km]
imperial : [mile]
sum_duration String Unit of total duration. Round down.
[sec]
average_pace String
Unit of average pace. Round down.
metric : [sec] (※[sec / km])
imperial : [sec] (※[sec / mile])
average_speed String
Unit of average speed. Round to three decimal places.
metric : [km / h]
imperial : [mile / 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.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 36 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
Error response
※about common error, please refer to Common error.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 37 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
3.4. Data
3.4.1. Export
Function
Export training data.
Corresponding subject
※about subject, please refer to Authentication.
user
Request
Request
GET /1/gps/users/{user_id}/export/{id}/ HTTP/1.1
parameter M/O description
user_id M User ID
id M Training ID
Query parameter
※M:Mandatory, O:Optional
parameter M/O description
time_zone O
Specify difference time from UTC [minute].
The output is in consideration of the time_zone.
※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].
The output is in consideration of the summer_time.
※default value 0. (According to specifications of GPX, the output of the time is usually UTC time.) ※the range is 0 to 120.
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 38 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
Header ※M:Mandatory, O:Optional
header M/O description
Host M go-wellness.epson.com
Accept M application/xml,text/plain;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
※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/
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 39 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
220
2014-02-24T00:11:49Z
…
(e.g.)time_zone = 540, summer_time=0 (Outside of the specifications of GPX)
※The time representation conforms to ISO 8601 specification.
Tokyo Marathon
8 degree, cloudy, a little windy
220
2014-02-24T09:10:54+09:00
220
2014-02-24T09:11:49+09:00
…
https://go-wellness.epson.com/neo-run/
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 40 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
Form Rev.0.3
(e.g.)time_zone = 0, summer_time=60 (Outside of the specifications of GPX)
※The time representation conforms to ISO 8601 specification.
Tokyo Marathon
8 degree, cloudy, a little windy
220
2014-02-24T01:10:54+01:00
220
2014-02-24T01:11:49+01:00
…
Error response
※about common error, please refer to Common error.
HTTP status code description
404 training_not_found Specified training does not exist. Check trainingID you request.
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/
(Control number: )
NeoRun Web API Interface Specifications Rev.1.1 Sheet : 41 Sensing System Operations Division / S PLANNING & DESIGN DEPARTMENT
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