Suggested refinements

[Chris Lukic]

Here's a quick list of some minor issues I've come across so far.

The list consists almost exclusively of minor refinements, and overall the API has been really easy to use so far. The only possible exception is the updated_at field which makes syncing somewhat cumbersome.

Activity object returned from search endpoint:

• the object returned from the search endpoint is distinct from the activity detail object and not just a subset (for example lat/lon is a comma separated string in the search result, but the detail contains fields: start_position_lat and start_position_lon) , but this object does not appear in the api documentation.

• distance, duration are string values. Should be floats.

• Suggest that updated_at should never be null, but rather should be initialized to the creation time and updated thereafter. This will allow api consumers to use it to gather all recent updates and new records. At present this will require two searches one for new records (which have null updated_at values) and a second query for updated records.

• It would be nice to have location values broken out as they're returned from geonames. location_city, location_country_name, location_country_code, location_topynym. At present the monolithic string value means that applications requiring greater granularity will need to re-geocode the lat/lon

• It would be convenient to have lat/lon as a paired array rather than a comma separated string

• End lat/lon position in addition to start lat/lon

• Good to have timezone offset in the search results activity summary, but it would be better to have the olsen time zone id (in addition/instead of)

Activity detail request:

• avg_heart_rate is a member of the root activity object, but avg_cadence is only available on the session/laps.

[ape...@magellangps.com]

Hello Chris,

The only possible exception is the updated_at field which makes syncing somewhat cumbersome.

I responded to this one in a previous email. More on this below.

Activity object returned from search endpoint:

• the object returned from the search endpoint is distinct from the activity detail object and not just a subset (for example lat/lon is a comma separated string in the search result, but the detail contains fields: start_position_lat and start_position_lon) , but this object does not appear in the api documentation.

Correct, just a subset so that you can subsequently query the desired activities in detail one at a time. Trying to keep the search response fairly lightweight. I already requested to have updated_at added to Activity Get response to be consistent. If there are other inconsistencies or documentation mistakes, I will have those corrected as well. Looks like there are a lot of them, actually, so I’ll work on getting those fixed (and that’s why we have versioning!).

• distance, duration are string values. Should be floats.

Added to the list of fixes.

• Suggest that updated_at should never be null, but rather should be initialized to the creation time and updated thereafter. This will allow api consumers to use it to gather all recent updates and new records. At present this will require two searches one for new records (which have null updated_at values) and a second query for updated records.

I responded to this one in a previous email. Like I said, we didn’t set the value for pre-existing activities (before 2013-12-30) because we didn’t track when they were updated, and therefore setting the value to uploaded_at would be misleading because those activities could very well have been updated since they were uploaded. I realize this requires 2 searches, but the alternative is false data. Trying to think of an ideal solution, but haven’t thought of one yet… lemme know if you think of one first!

• It would be nice to have location values broken out as they're returned from geonames. location_city, location_country_name, location_country_code, location_topynym. At present the monolithic string value means that applications requiring greater granularity will need to re-geocode the lat/lon

Hmmm… we simply return location name since that’s all we use on our Magellan Active website. Is this a nice to have just in case you want to use those values, or will it actually save you a call to geonames? No sense in both of us paying for the call.

• It would be convenient to have lat/lon as a paired array rather than a comma separated string

I here ya, but with all the little changes, for now will just stick to same as Activity Get response (start_position_lat & start_position_lon). Will re-assess after all the other changes.

• End lat/lon position in addition to start lat/lon

In the response or do you also want to be able to filter on the end location as well like you can with start position?

• Good to have timezone offset in the search results activity summary, but it would be better to have the olsen time zone id (in addition/instead of)

We return timezone_id for Activity Get which is the olsen timezone from geonames. So you just want this included in the Search as well?

Activity detail request:

• avg_heart_rate is a member of the root activity object, but avg_cadence is only available on the session/laps.

Or power, grade, vertical speed, or any other data fields that may not make much sense when averaged across sessions of different sport types within a single activity. Our activity object starts with FIT as the basis for its structure (activity, session, laps, readings/records). FIT contains heart rate at the activity level, but not power or cadence, so we do the same. If you take a look at a multi-session activity on Magellan Active, you will see this reflected in the contents of the Activity Summary (View All Stats) data shown.

http://active.magellangps.com/activity/2231

So no plans to add all of the session level fields to the activity level as well. If there’s only 1 session, it’s easiest to simply iterate through that 1 and only session, rather than pick and choose some activity data from the activity level and others from the session level (except for activity metadata of course such as uploaded_at, device source, etc.).

--

Anthony (Tony) Pelosi

Magellan GPS, Fitness Division

Product Development Lead

ape...@magellangps.com

415-644-8969

--
You received this message because you are subscribed to the Google Groups "Magellan Active Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to magellan-active-dev...@googlegroups.com.
To post to this group, send email to magellan-acti...@googlegroups.com.
Visit this group at http://groups.google.com/group/magellan-active-developers.
For more options, visit https://groups.google.com/d/optout.