The Search API allows for high performance searching of various Triathlon.org collections. As the service is powered by Algolia the Search API is suitable for returning results from front-end search applications as results will take into account typos and other ranking criteria.
The Search API has a single method and is invoked by appending the collection to be searched onto the /search/{collection} endpoint.
The Search API is designed to be used in conjunction with each API's Listings call e.g. Athlete Listings where a more fuzzy style of search is required e.g. for search boxes allowing user input. If you simply wish to find all athletes in USA then you will fare better with the Athlete Listings call as false positives will not be returned.
Available Collections
The following collections are available to be searched. By simply providing just a collection and query you will return full search results which factor in typos and other custom ranking criteria to return the most relevant results for your application.
- athletes
- courses
- events
- federations
- news
- videos
curl --header "apikey: YOUR_APP_KEY" "https://api.triathlon.org/v1/search/events?query=london"
Each search result will include a basic object of that type e.g. a basic Federation object is returned for all federation searches allowing you to integrate the search API with other available APIs.
Dates
For the following collections you may specify a start_date and end_date parameter that limits the returned results between two dates (also see the filters section below if you just want a specific month and year).
- courses
- events
- news
- videos
The following example restricts returned events search results between January and February of 2015.
curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/search/events?start_date=2015-01-01&end_date=2015-02-01"
Filters
Filters may also be specified to further restrict search results (or in place of a query). The parameters that you may filter on are dependent on the collection being search and are outlined in the following table:
| Collection | Filterable Attributes |
|---|---|
| athletes | athlete_country_name athlete_gender |
| courses | course_country course_language course_region_name course_categories.cat_name year month |
| events | event_region_name event_country event_categories.cat_name specification.cat_name sport.cat_name year * month |
| federations | federation_region_name federation_affiliation_status |
| news | news_categories.cat_name year * month |
| videos | video_categories.cat_name year * month |
Each filter must be comprised of key value pair seperated by a comma. Multiple filters may be specified by including a |. For example to filter the athletes index to only return male athletes the following filter would be used filters=athlete_gender,male or to restrict courses or events to a certain year you may apply the filter filters=year,2014.
To restrict events to a certain month and year you may provide a multiple filter such as `filters=year,2014|month,March' (alternatively you could set the start and end date appropriately).
As the search has been optimized for performance only certain attributes may be filtered on as specified in the table above and if you require additional fine-grain filtering you should consult the available Listings API methods in the underlying API.
The following example returns the same date filter that was applied in the Dates section.
curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/search/events?filters=year,2015|month,January"
Geo-Searching
Geo-Searching is only available for the courses and events collections
You may provide a location, specified as lat,long to add geo-searching capabilities to your search. Geo-searching is only available for the courses and events indexes.
You may also specify an optional distance parameter. Distances are provided in km and will restrict results to only those entries that fall within the distance radius.
If you do not provide a distance parameter then the location is taken into account when ranking search results. For example if no query is provided it will simply return the closes entries but if a query is also specified both the query and location will be taken into account when returning the results for the best possible search results.
For all geo-searching queries a search_distance key is returned indicating the distance from the specified location to the search result.
For example, the following query searches for events within 100km of London, UK:
curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/search/events?location=51.500152,-0.126236&distance=100"