{"__v":89,"_id":"564b868fdda79a19000f2679","category":{"__v":3,"_id":"564a70dc4cd0521700523edf","pages":["564b868fdda79a19000f2679","564b86a0e6c67c2f0038366e","56b4dc1e3d5f130d00dad161"],"project":"55773a5ba042551900b002cb","version":"55773a5ba042551900b002ce","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-11-17T00:12:12.009Z","from_sync":false,"order":12,"slug":"search-api","title":"Search API"},"parentDoc":null,"project":"55773a5ba042551900b002cb","user":"546d17e2eb9cfd1400dd4529","version":{"__v":17,"_id":"55773a5ba042551900b002ce","project":"55773a5ba042551900b002cb","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"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Motherboard","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-17T19:57:03.300Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"The **Search API** allows for high performance searching of various Triathlon.org collections. As the service is powered by [Algolia](https://www.algolia.com/) the Search API is suitable for returning results from front-end search applications as results will take into account typos and other ranking criteria.\n\nThe Search API has a [single method](https://developers.triathlon.org/docs/search-results) and is invoked by appending the collection to be searched onto the /search/{collection} endpoint.\n\nThe Search API is designed to be used in conjunction with each API's Listings call e.g. [Athlete Listings](https://developers.triathlon.org/docs/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.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"An example of the search API in action is available on the [WTS athletes search](http://wts.triathlon.org/athletes/search) page.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available Collections\"\n}\n[/block]\nThe 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.\n\n* athletes\n* courses\n* events\n* federations\n* news\n* videos\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: YOUR_APP_KEY\\\" \\\"https://api.triathlon.org/v1/search/events?query=london\\\"\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nEach search result will include a *basic object* of that type e.g. a [basic Federation object](https://developers.triathlon.org/docs/federation-api-overview#basic-federation-object) is returned for all federation searches allowing you to integrate the search API with other available APIs.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Dates\"\n}\n[/block]\nFor 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).\n\n* courses\n* events\n* news\n* videos\n\nThe following example restricts returned events search results between January and February of 2015.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/search/events?start_date=2015-01-01&end_date=2015-02-01\\\"\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Filters\"\n}\n[/block]\nFilters 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:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Collection\",\n    \"0-0\": \"athletes\",\n    \"1-0\": \"courses\",\n    \"2-0\": \"events\",\n    \"3-0\": \"federations\",\n    \"4-0\": \"news\",\n    \"5-0\": \"videos\",\n    \"h-1\": \"Filterable Attributes\",\n    \"1-1\": \"* course_country\\n* course_language\\n* course_region_name\\n* course_categories.cat_name\\n* year\\n* month\",\n    \"5-1\": \"* video_categories.cat_name\\n* year\\n* month\",\n    \"2-1\": \"* event_region_name\\n* event_country\\n* event_categories.cat_name\\n* specification.cat_name\\n* sport.cat_name\\n* year\\n* month\",\n    \"3-1\": \"* federation_region_name\\n* federation_affiliation_status\",\n    \"4-1\": \"* news_categories.cat_name\\n* year\\n* month\",\n    \"0-1\": \"* athlete_country_name\\n* athlete_gender\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\nEach 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`. \n\nTo 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).\n\nAs 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.\n\nThe following example returns the same date filter that was applied in the [Dates section](https://developers.triathlon.org/docs/search-api-overview#dates).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/search/events?filters=year,2015|month,January\\\"\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Geo-Searching\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Geo-Searching is only available for the courses and events collections\"\n}\n[/block]\nYou 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.\n\nYou 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.\n\nIf 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.\n\nFor all geo-searching queries a `search_distance` key is returned indicating the distance from the specified location to the search result.\n\nFor example, the following query searches for events within 100km of London, UK:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"apikey: [[app:key]]\\\" \\\"https://api.triathlon.org/v1/search/events?location=51.500152,-0.126236&distance=100\\\"\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"search-api-overview","type":"basic","title":"Search API Overview"}

Search API Overview


The **Search API** allows for high performance searching of various Triathlon.org collections. As the service is powered by [Algolia](https://www.algolia.com/) 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](https://developers.triathlon.org/docs/search-results) 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](https://developers.triathlon.org/docs/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. [block:callout] { "type": "success", "body": "An example of the search API in action is available on the [WTS athletes search](http://wts.triathlon.org/athletes/search) page." } [/block] [block:api-header] { "type": "basic", "title": "Available Collections" } [/block] 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 [block:code] { "codes": [ { "code": "curl --header \"apikey: YOUR_APP_KEY\" \"https://api.triathlon.org/v1/search/events?query=london\"", "language": "json" } ] } [/block] Each search result will include a *basic object* of that type e.g. a [basic Federation object](https://developers.triathlon.org/docs/federation-api-overview#basic-federation-object) is returned for all federation searches allowing you to integrate the search API with other available APIs. [block:api-header] { "type": "basic", "title": "Dates" } [/block] 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. [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/search/events?start_date=2015-01-01&end_date=2015-02-01\"", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Filters" } [/block] 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: [block:parameters] { "data": { "h-0": "Collection", "0-0": "athletes", "1-0": "courses", "2-0": "events", "3-0": "federations", "4-0": "news", "5-0": "videos", "h-1": "Filterable Attributes", "1-1": "* course_country\n* course_language\n* course_region_name\n* course_categories.cat_name\n* year\n* month", "5-1": "* video_categories.cat_name\n* year\n* month", "2-1": "* event_region_name\n* event_country\n* event_categories.cat_name\n* specification.cat_name\n* sport.cat_name\n* year\n* month", "3-1": "* federation_region_name\n* federation_affiliation_status", "4-1": "* news_categories.cat_name\n* year\n* month", "0-1": "* athlete_country_name\n* athlete_gender" }, "cols": 2, "rows": 6 } [/block] 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](https://developers.triathlon.org/docs/search-api-overview#dates). [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/search/events?filters=year,2015|month,January\"", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Geo-Searching" } [/block] [block:callout] { "type": "info", "title": "Geo-Searching is only available for the courses and events collections" } [/block] 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: [block:code] { "codes": [ { "code": "curl --header \"apikey: [[app:key]]\" \"https://api.triathlon.org/v1/search/events?location=51.500152,-0.126236&distance=100\"", "language": "json" } ] } [/block]