{"_id":"563a50051846790d0089535e","version":{"_id":"55773a5ba042551900b002ce","project":"55773a5ba042551900b002cb","__v":18,"createdAt":"2015-06-09T19:11:23.764Z","releaseDate":"2015-06-09T19:11:23.764Z","categories":["55773a5ca042551900b002cf","55773a6ce6063e0d00481380","55773ab007e7110d001043ec","55773abaa042551900b002d5","55773ac207e7110d001043ed","55773acb07e7110d001043ee","55773ad3a042551900b002d6","55773adce6063e0d00481383","55773ae4a042551900b002d7","55773af307e7110d001043ef","55773af907e7110d001043f0","55773b0407e7110d001043f1","563a4f7ad25e8919005f3f39","563a4fcaa19edf0d00972321","564a70dc4cd0521700523edf","564b797bcc472d0d00da9435","564b855b766d4923004e1fd1","59cd4b81935249001c77c48e"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Motherboard","version_clean":"1.0.0","version":"1"},"project":"55773a5ba042551900b002cb","category":{"_id":"563a4fcaa19edf0d00972321","__v":6,"pages":["563a50051846790d0089535e","564ba1cf5cc43717009bcfe9","565a60d433140c0d0033930c","5673222e47f7010d005bfd7c","56afd2f5d21e9c0d00b62962","56be2bff6cae110d00190c05"],"project":"55773a5ba042551900b002cb","version":"55773a5ba042551900b002ce","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-04T18:34:50.832Z","from_sync":false,"order":1,"slug":"guides","title":"Guides"},"parentDoc":null,"user":"546d17e2eb9cfd1400dd4529","__v":4,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-04T18:35:49.906Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The breadth of analysis types may make the Statistics API daunting to use so we have provided a few useful examples to demonstrate the API in action.\n\nOf course you cannot perform all types of analysis from this API but you may use the data extraction as a starting point for building even richer analysis on top of the initial export (e.g. see the [winning margins](#data-extraction) example below).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Additional Program Data\",\n  \"body\": \"We are in the process of adding additional information to each of the programs such as atmospheric conditions, distances and other data. This will allow for an even deeper querying experience. Please see [this update for further information](http://statistics.triathlon.org/v1.0/blog/atmospheric-conditions-data-update).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Query Examples\"\n}\n[/block]\n**How many WTS events have there been?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count_unique&target_property=event.name\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhich returns the following [response ](responses-and-status-codes)(the answer is 53):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{  \\n   \\\"code\\\":200,\\n   \\\"status\\\":\\\"success\\\",\\n   \\\"data\\\":53\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**What is the average age of WTS winners vs. Format (Sprint vs Standard)?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=average&target_property=athlete.age&group_by=format|athlete.gender\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhich returns the average ages of Sprint and Standard distances winners grouped by format and gender.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"code\\\":200,\\n   \\\"status\\\":\\\"success\\\",\\n   \\\"data\\\":[\\n      {\\n         \\\"athlete.gender\\\":\\\"female\\\",\\n         \\\"result\\\":27.42723880597,\\n         \\\"format\\\":\\\"Sprint\\\"\\n      },\\n      {\\n         \\\"athlete.gender\\\":\\\"male\\\",\\n         \\\"result\\\":27.492091388401,\\n         \\\"format\\\":\\\"Sprint\\\"\\n      },\\n      {\\n         \\\"athlete.gender\\\":\\\"female\\\",\\n         \\\"result\\\":30.072972972973,\\n         \\\"format\\\":\\\"Standard\\\"\\n      },\\n      {\\n         \\\"athlete.gender\\\":\\\"male\\\",\\n         \\\"result\\\":29.991626794258,\\n         \\\"format\\\":\\\"Standard\\\"\\n      }\\n   ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**How many top 10 results have each nation obtained this year?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=position,lte,10&group_by=athlete.country|athlete.gender&timeframe=this_year\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TKuDn9n2SQGJcEQDs6Cd_top10finishes.png\",\n        \"top10finishes.png\",\n        \"800\",\n        \"601\",\n        \"#47aab2\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\n**What is the best ever World Triathlon Series finish for a Japanese male athlete?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.country,eq,JPN|athlete.gender,eq,male\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThis will return the result for the best finishing position (which is 7th at the time of writing). This leads naturally to the question, who and where was it? There are a couple of ways of answering that question... Firstly you could simply extract the best (i.e. minimum) finish for all Japanese athletes (by grouping by athlete.name and optionally event.name) and find the minimum position from the resulting array. Secondly, knowing the minimum finishing position you could construct a second query to find just the result(s) in question e.g.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.country,eq,JPN|athlete.gender,eq,male|position,eq,7&group_by=athlete.name|event.name\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThis returns the required information (note: if more than one athlete had finished in 7th position, or it had occurred at multiple events, an array would have been returned of all 7th place finishes).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{  \\n   \\\"code\\\":200,\\n   \\\"status\\\":\\\"success\\\",\\n   \\\"data\\\":[  \\n      {  \\n         \\\"event.name\\\":\\\"2012 ITU World Triathlon Madrid\\\",\\n         \\\"athlete.name\\\":\\\"Hirokatsu Tayama\\\",\\n         \\\"result\\\":7\\n      }\\n   ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**How many of each World Triathlon Series medals does Alistair Brownlee have**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"Alistair Brownlee Total Podiums\"\n    },\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" https://proxy.api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position|year\",\n      \"language\": \"curl\",\n      \"name\": \"Grouped by Year\"\n    },\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" https://proxy.api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position|format\",\n      \"language\": \"curl\",\n      \"name\": \"Grouped by format\"\n    }\n  ]\n}\n[/block]\n**How many top 10 finishes have USA women had per year of the World Triathlon Series**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.country,eq,USA|athlete.gender,eq,female|position,lte,10&timeframe=this_7_years&interval=yearly\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nNote: You could achieve the same result above simply by grouping by the year property but this example demonstrates the interval function.\n\n**Count how many times a group of athletes have raced**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.last,in,Brownlee,Mola,Frodeno\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**How many results are without a swim time?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=splits.swim,exists,false\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhen a property is not available you may check for it's existence with the **exists ** filter. The majority of missing information is due to athletes not completing that section of the event. However there are certain instances where lost timing chips have caused a loss of data.\n\n**How does Jonathan Brownlee perform within 1000 miles of his hometown Leeds, UK?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Jonathan Brownlee|location,within,1000,53.801277,-1.548567&group_by=position\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Data Extraction\"\n}\n[/block]\nYou won't be able to answer all your questions via a single API call e.g. what is the largest winning margin in a WTS race? In such cases you will need to extract the relevant data and either perform your own analysis of the results or script follow up queries to arrive at the final result. There are often a multitude of ways to solve the same problem and we will consider the simplest implementation to finding the largest winning margin:\n\n**First, list all WTS Events**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=count_unique&target_property=event.name&group_by=event.name|program.id|program.name\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"All WTS Events\"\n    }\n  ]\n}\n[/block]\nWith this query we have a list of all WTS races that have occurred including the unique program.id which may be used to extract the winning and second place times. We can then loop through each result making a call to each program.id and store the result.\n\n**Winning and second place times for each program**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=program.id,eq,4818|position,lte,2&group_by=athlete.name|finish_time\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"Program Results\"\n    }\n  ]\n}\n[/block]\nClearly then it is a *simple* task of calculating the difference between the winning time and second place time for all programs and sorting by the difference (note: if you wish to check your working the result is Emma Snowsill at the 2010 Grand Final in Budapest where she bested Emma Moffatt by 102 seconds!)\n\n**Extract an athlete's results**\n\nWe can use the group_by property to extract all the different information we require.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.name,eq,Gwen%20Jorgensen&group_by=event.name|date|format|event.id|finish_time&timeframe=this_year\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**How does Richard Murray fare when wearing a wetsuit?**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/statistics/results?analysis=average&target_property=position&filters=athlete.name,eq,Richard%20Murray&group_by=program.wetsuit\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Need more ideas?\"\n}\n[/block]\n* Is Javier Gomez Noya a morning or evening person? - compare an athlete's results based on the start time of the race (program.start_time)\n* How have the average swim times changed over the course of the Series?\n* Who peaks early in the year? - group athletes' results via months to spot trends","excerpt":"","slug":"getting-started-with-statistics-api","type":"basic","title":"Getting Started with Statistics API"}

Getting Started with Statistics API


The breadth of analysis types may make the Statistics API daunting to use so we have provided a few useful examples to demonstrate the API in action. Of course you cannot perform all types of analysis from this API but you may use the data extraction as a starting point for building even richer analysis on top of the initial export (e.g. see the [winning margins](#data-extraction) example below). [block:callout] { "type": "info", "title": "Additional Program Data", "body": "We are in the process of adding additional information to each of the programs such as atmospheric conditions, distances and other data. This will allow for an even deeper querying experience. Please see [this update for further information](http://statistics.triathlon.org/v1.0/blog/atmospheric-conditions-data-update)." } [/block] [block:api-header] { "type": "basic", "title": "Query Examples" } [/block] **How many WTS events have there been?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count_unique&target_property=event.name\"", "language": "curl" } ] } [/block] Which returns the following [response ](responses-and-status-codes)(the answer is 53): [block:code] { "codes": [ { "code": "{ \n \"code\":200,\n \"status\":\"success\",\n \"data\":53\n}", "language": "json" } ] } [/block] **What is the average age of WTS winners vs. Format (Sprint vs Standard)?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=average&target_property=athlete.age&group_by=format|athlete.gender\"", "language": "curl" } ] } [/block] Which returns the average ages of Sprint and Standard distances winners grouped by format and gender. [block:code] { "codes": [ { "code": "{\n \"code\":200,\n \"status\":\"success\",\n \"data\":[\n {\n \"athlete.gender\":\"female\",\n \"result\":27.42723880597,\n \"format\":\"Sprint\"\n },\n {\n \"athlete.gender\":\"male\",\n \"result\":27.492091388401,\n \"format\":\"Sprint\"\n },\n {\n \"athlete.gender\":\"female\",\n \"result\":30.072972972973,\n \"format\":\"Standard\"\n },\n {\n \"athlete.gender\":\"male\",\n \"result\":29.991626794258,\n \"format\":\"Standard\"\n }\n ]\n}", "language": "json" } ] } [/block] **How many top 10 results have each nation obtained this year?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=position,lte,10&group_by=athlete.country|athlete.gender&timeframe=this_year\"", "language": "curl" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/TKuDn9n2SQGJcEQDs6Cd_top10finishes.png", "top10finishes.png", "800", "601", "#47aab2", "" ], "caption": "" } ] } [/block] **What is the best ever World Triathlon Series finish for a Japanese male athlete?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.country,eq,JPN|athlete.gender,eq,male\"", "language": "curl" } ] } [/block] This will return the result for the best finishing position (which is 7th at the time of writing). This leads naturally to the question, who and where was it? There are a couple of ways of answering that question... Firstly you could simply extract the best (i.e. minimum) finish for all Japanese athletes (by grouping by athlete.name and optionally event.name) and find the minimum position from the resulting array. Secondly, knowing the minimum finishing position you could construct a second query to find just the result(s) in question e.g. [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.country,eq,JPN|athlete.gender,eq,male|position,eq,7&group_by=athlete.name|event.name\"", "language": "curl" } ] } [/block] This returns the required information (note: if more than one athlete had finished in 7th position, or it had occurred at multiple events, an array would have been returned of all 7th place finishes). [block:code] { "codes": [ { "code": "{ \n \"code\":200,\n \"status\":\"success\",\n \"data\":[ \n { \n \"event.name\":\"2012 ITU World Triathlon Madrid\",\n \"athlete.name\":\"Hirokatsu Tayama\",\n \"result\":7\n }\n ]\n}", "language": "json" } ] } [/block] **How many of each World Triathlon Series medals does Alistair Brownlee have** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position\"", "language": "curl", "name": "Alistair Brownlee Total Podiums" }, { "code": "curl --header \"apikey: [[app:key]]\" https://proxy.api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position|year", "language": "curl", "name": "Grouped by Year" }, { "code": "curl --header \"apikey: [[app:key]]\" https://proxy.api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Alistair%20Brownlee|position,lte,3&group_by=position|format", "language": "curl", "name": "Grouped by format" } ] } [/block] **How many top 10 finishes have USA women had per year of the World Triathlon Series** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.country,eq,USA|athlete.gender,eq,female|position,lte,10&timeframe=this_7_years&interval=yearly\"", "language": "curl" } ] } [/block] Note: You could achieve the same result above simply by grouping by the year property but this example demonstrates the interval function. **Count how many times a group of athletes have raced** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.last,in,Brownlee,Mola,Frodeno\"", "language": "curl" } ] } [/block] **How many results are without a swim time?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=splits.swim,exists,false\"", "language": "curl" } ] } [/block] When a property is not available you may check for it's existence with the **exists ** filter. The majority of missing information is due to athletes not completing that section of the event. However there are certain instances where lost timing chips have caused a loss of data. **How does Jonathan Brownlee perform within 1000 miles of his hometown Leeds, UK?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count&filters=athlete.name,eq,Jonathan Brownlee|location,within,1000,53.801277,-1.548567&group_by=position\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Data Extraction" } [/block] You won't be able to answer all your questions via a single API call e.g. what is the largest winning margin in a WTS race? In such cases you will need to extract the relevant data and either perform your own analysis of the results or script follow up queries to arrive at the final result. There are often a multitude of ways to solve the same problem and we will consider the simplest implementation to finding the largest winning margin: **First, list all WTS Events** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=count_unique&target_property=event.name&group_by=event.name|program.id|program.name\"", "language": "curl", "name": "All WTS Events" } ] } [/block] With this query we have a list of all WTS races that have occurred including the unique program.id which may be used to extract the winning and second place times. We can then loop through each result making a call to each program.id and store the result. **Winning and second place times for each program** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=program.id,eq,4818|position,lte,2&group_by=athlete.name|finish_time\"", "language": "curl", "name": "Program Results" } ] } [/block] Clearly then it is a *simple* task of calculating the difference between the winning time and second place time for all programs and sorting by the difference (note: if you wish to check your working the result is Emma Snowsill at the 2010 Grand Final in Budapest where she bested Emma Moffatt by 102 seconds!) **Extract an athlete's results** We can use the group_by property to extract all the different information we require. [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=minimum&target_property=position&filters=athlete.name,eq,Gwen%20Jorgensen&group_by=event.name|date|format|event.id|finish_time&timeframe=this_year\"", "language": "curl" } ] } [/block] **How does Richard Murray fare when wearing a wetsuit?** [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/statistics/results?analysis=average&target_property=position&filters=athlete.name,eq,Richard%20Murray&group_by=program.wetsuit\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Need more ideas?" } [/block] * Is Javier Gomez Noya a morning or evening person? - compare an athlete's results based on the start time of the race (program.start_time) * How have the average swim times changed over the course of the Series? * Who peaks early in the year? - group athletes' results via months to spot trends