Using the Search API

The Search API is the fastest and simplest way to access resources on the Triathlon.org API platform. The Search API is best suited for front-end applications where users are, for example, searching for events or athlete names as typos will be factored in when returning search results and custom ranking criteria are used to determine the most relevant results.

Let's say for example we want to find any athletes named Brownlee. Using the Search API and the athletes collection we can conduct the following request:

curl --header "apikey: YOUR_APP_KEY" "https://api.triathlon.org/v1/search/athletes?query=brownlee"

Which will return an array of basic athlete objects. Results are ordered via custom ranking criteria but more weight will be placed on elite athletes.

{
    "code": 200,
    "status": "success",
    "total": 16,
    "per_page": 10,
    "current_page": 1,
    "last_page": 2,
    "next_page_url": "https://api.triathlon.org/v1/search?query=brownlee&collection=athletes&page=2",
    "prev_page_url": null,
    "from": 1,
    "to": 10,
    "data": [
        {
            "athlete_id": 7788,
            "athlete_title": "Alistair Brownlee",
            "athlete_slug": "alistair_brownlee",
            "athlete_first": "Alistair",
            "athlete_last": "Brownlee",
            "athlete_country_id": 292,
            "athlete_gender": "male",
            "athlete_yob": "1988",
            "validated": false,
            "athlete_profile_image": "http://www.triathlon.org/images/athlete_thumbs/Brownlee.png",
            "athlete_noc": "GBR",
            "athlete_country_name": "Great Britain",
            "athlete_country_isoa2": "GB",
            "athlete_listing": "http://www.triathlon.org/athletes/profile/7788/alistair_brownlee",
            "athlete_flag": "https://f9ca11ef49c28681fc01-0acbf57e00c47a50e70a1acb89e86c89.ssl.cf1.rackcdn.com/images/icons/gb.png",
            "athlete_api_listing": "https://api.triathlon.org/v1/v1/athletes/7788",
            "athlete_categories": [
                42
            ]
        }
    ]
}

The resulting list of 16 athletes that were returned contain both age-group athletes (defined as those without a points list ranking) as well as potential matches considering misspellings such as Jody Brownley though naturally they would be ranked lower in search results.

The Search API also allows for additional filters to further restrict results, which for athletes are athlete_country_name and athlete_gender. So restricting to male Brownlees in Great Britain the following request would be made:

curl --header "apikey: YOUR_APP_KEY" "https://api.triathlon.org/v1/search/athletes?query=brownlee&filters=athlete_gender,male|athlete_country_name,Great Britain"

Other collections i.e. videos or events have different filterable options with events for example in addition allowing filtering on dates and even geolocation to find nearest event etc... So the following request would return events within 250km of London,UK during 2015

curl --header "apikey: YOUR_APP_KEY" "https://api.triathlon.org/v1/search/events?location=51.500152,-0.126236&distance=250&filters=year,2015"