In the original version of Xeno-canto, a very simple web service was provided. In 2013, a more full-featured, RESTful JSON-based API was introduced. Over the years, both the search options and the data returned by API v2 were greatly expanded.
The downside of a popular API is that its use may negatively affect general web site performance. This forced us to add a rate limiter. Another factor affecting performance was the use of generic simple search terms. These are well-suited for the site's general search option, but an API is best served with precise queries. Finally, unrestricted access to the API also contributed to degraded performance.
Creating a new v3 of the API allowed us to address these issues and more:
per_page to adjust this from 50 to 500 results per page.The endpoint for the webservice is at https://xeno-canto.org/api/3/recordings.
There are four possible query parameters for this API.
The query parameter is required and must be non-empty. The query parameter must be a search string in the format described on the search tips page.
The key parameter is new to API v3 and is required and must be non-empty as well. A key is available to all registered XC members who have verified their email address. Do not share your key with others and take care not to publish it in any git repositories, as prolonged abuse of the API may result in a warning and ultimately in revocation of your key. If you have accidentally shared your key, please for a new one.
Developers building applications on the XC API are encouraged to create a key for their app rather than to use a personal key.The per_page parameter is optional, determining the number of results per page. Valid values for this parameter range between 50 and 500, with a default of 100 when not provided.
The page parameter is optional as well and is only needed if the results from a given search don't fit in a single page. If specified, page must be an integer between 1 and results.numPages (see results format below for details).
The response is returned with a payload in JSON format. The details are shown below.
For a successful query, a HTTP 200 response code will be returned, with a payload in the following format:
{
"numRecordings": "1",
"numSpecies": "1",
"page": 1,
"numPages": 1,
"recordings": [
...,
Array of Recording objects (see below),
...
]
}
This JSON object will contain details about the recordings found with the given query. For performance reasons, the number of recordings returned for a given query will be limited. If the limit is lower than the total number of results, they will be split into 'pages'. To fetch the next page of results, you must append the page query parameter as specified above.
A brief description of the fields:
Each object in the recordings array mentioned above has the following format:
{
"id": "694038",
"gen": "Troglodytes",
"sp": "troglodytes",
"ssp": "",
"grp": "birds",
"en": "Eurasian Wren",
"rec": "Jacobo Ramil MIllarengo",
"cnt": "Spain",
"loc": "Sisalde, Ames, A Coruña, Galicia",
"lat": "42.8373",
"lon": "-8.652",
"alt": "30",
"type": "song",
"sex": "male",
"stage": "adult",
"method": "field recording",
"url": "//xeno-canto.org/694038",
"file": "//xeno-canto.org/694038/download",
"file-name": "XC694038-211223_02Carrizo variacións dunha frase bastante stereotipada siteD 9.30 Sisalde.mp3",
"sono": {
"small": "//xeno-canto.org/sounds/spectrograms/LHCOINSOBZ/694038/grey-small.png",
"med": "//xeno-canto.org/sounds/spectrograms/LHCOINSOBZ/694038/grey-medium.png",
"large": "//xeno-canto.org/sounds/spectrograms/LHCOINSOBZ/694038/colour.png",
"full": ""
},
"osci": {
"small": "", // Always empty, dedicated oscillograms have been phased out
"med": "",
"large": ""
},
"lic": "//creativecommons.org/licenses/by-nc-sa/4.0/",
"q": "A",
"length": "4:08",
"time": "09:30",
"date": "2021-12-23",
"uploaded": "2021-12-27",
"also": [
"Turdus viscivorus",
"Turdus iliacus",
"Parus major"
],
"rmk": "A male repeat a stereotyped phrase with few syllabic variation. HPF 270 Hz. It´s raining.",
"animal-seen": "yes",
"playback-used": "no",
"temp": "",
"regnr": "",
"auto": "unknown",
"dvc": "",
"mic": "",
"smp": "44100",
"annotation-set": {
"set_name": "Annotation set for XC694038",
"set_creator": "W.P. Vellinga",
"set_creation_date": "2026-03-18 00:00:00",
"set_remarks": "Metadata of the original set is provided for each individual annotation",
"annotations": [
{
"annotation_xc_id": 1,
"xc_nr": "694038",
"scientific_name": "Troglodytes troglodytes",
"annotator": "W.P. Vellinga",
"start_time": 0.27,
"end_time": 3.33,
"frequency_high": 10204,
"frequency_low": 2551,
"sound_type": "song",
"sex": "male",
"life_stage": "adult",
"annotation_remarks": "audible rain drops",
"original_set_metadata": {
"set_name": "Demonstration set",
"set_creator": "W.P. Vellinga",
"set_owner": "W.P. Vellinga",
"set_license": "CC-BY-NC-4.0",
"set_uri": "//xeno-canto.org/annotation/set/1",
"set_creation_date": "2026-03-01 00:00:00"
}
},
{
"annotation_xc_id": 2,
"xc_nr": "694038",
"scientific_name": "Troglodytes troglodytes",
"annotator": "W.P. Vellinga",
"start_time": 7.65,
"end_time": 10.28,
"frequency_high": 9962,
"frequency_low": 2278,
"sound_type": "song",
"sex": "male",
"life_stage": "adult",
"annotation_remarks": "rain drops",
"original_set_metadata": {
"set_name": "Demonstration set",
"set_creator": "W.P. Vellinga",
"set_owner": "W.P. Vellinga",
"set_license": "CC-BY-NC-4.0",
"set_uri": "//xeno-canto.org/annotation/set/1",
"set_creation_date": "2026-03-01 00:00:00"
}
},
{
"annotation_xc_id": 3,
"xc_nr": "694038",
"scientific_name": "Periparus ater",
"annotator": "W.P. Vellinga",
"start_time": 10.28,
"end_time": 11.92,
"frequency_high": 6651,
"frequency_low": 3675,
"sound_type": "song",
"sex": null,
"life_stage": null,
"annotation_remarks": "rain drops",
"original_set_metadata": {
"set_name": "Demonstration set",
"set_creator": "W.P. Vellinga",
"set_owner": "W.P. Vellinga",
"set_license": "CC-BY-NC-4.0",
"set_uri": "//xeno-canto.org/annotation/set/1",
"set_creation_date": "2026-03-01 00:00:00"
}
}
]
}
The following is a detailed description of the fields of this object:
The payload for restricted species is redacted. Given their vulnerability, the exact location of the recording and the recording itself are not returned for such species. An extra _meta tag indicates this:
{
"_meta": {
"redacted_fields": {
"loc": "restricted_species",
"lat": "restricted_species",
"lon": "restricted_species",
"file": "restricted_species",
"file-name": "restricted_species"
}
}
}
In case of an error, a HTTP 400 or 500 response code will be returned (depending on whether the error was a client or server error). The payload returned will be of the following form:
{
"error": {
"code":"missing_parameter",
"message":"No query specified"
}
}
The code parameter will be an identifier for the error, and message will offer some additional explanatory details.
The API uses (a combination of) search tags to precisely define the query. It's a good idea to familiarize yourself with the options these tags provide, as their use isn't exactly straightforward!
Before diving into the examples, we need to reiterate that searching for species without tags (as was the default for API v2) is now discontinued. Another important fact to bear in mind is that you must quote search tags consisting of multiple terms, or terms using operators (=, < or >). Again, see Search tips for more information. Finally, in API v3 you will need to append your key to every API call. Off to a rough start, as these three examples fail:
Likely the most often used API call is to fetch recordings for a specific species. While in API v2 this was done by just providing the species name without tags, in v3 this requires the sp tag (for species) or combination of gen (for genus) and sp tags. The sp tag can be used for a complete species name (remember: between quotes); in combination with a gen tag (resulting in essentially the same query); or for just the specific epithet.
Moving on to working examples, both
If you want to narrow down the previous example to just birds, you can add the grp tag. Thus
will search for all birds having the specific epithet fuscus. See the Search tips for all possible grp options.A search for Larus fuscus may still be to broad if you are only interested in recordings of the nominate Baltic Gull Larus fuscus fuscus. In that case, append the ssp tag to your query, or use a triplet similar to the pair of the sp tag:
Conversely, if you want to broaden your search to all gulls, not just those from the genus Larus, this is now availabe with the new fam tag:
Finally, it is also possible to search for taxa using their vernacular name in English using the en tag. There are good reasons to avoid this type of search though. First, unlike scientific names, common names are not guaranteed to be unique. Second, this search option tends to be slow, as it involves a wildcard search by default. Compare the performance of two queries on 'lesser black-backed gull', one using the default wildcard search, the other including the matches operator:
There are several ways to geographically limit your queries. In order of scale, they are area (world area, more or less at continental level), cnt (country) and loc (location). The examples cover land mammals from Asia, frogs from Surinam and birds from Suffolk Coastal District, Suffolk, England.
Alternatively, you can base your query on lat (latitude), lon (longitude), or a combination thereof. The examples return birds recorded above the Arctic Circle (65° N), bats recorded around 4.2884N, 36.2626E (in Kenya) and grasshoppers recorded in a bounding box covering parts of Sumatra, Malaysia and Singapore:
The year and month tags allow filtering on recording dates before, after or between specific periods. The since tag can be used to search for date of uploading. Examples are frogs recorded before 1970, European birds from the family of Finches recorded after August, or all land mammal recordings from last month:
The type (sound type), sex and stage (life stage) tags specify several sound and animal-related characters. The various options are listed under Tips. Examples here are female bird songs from the Americas or social calls of juvenile bats:
Several tags can be used to search for the property of sound files themselves. q for sound quality (on an A-E scale), len for length (in seconds) and smp for sample rate of the recording. The examples show the results for top quality soundscapes lasting at least an hour and high-frequency grasshopper recordings from Malaysia with quality A and B.
The list of tags used in these examples is incomplete. Check Search tips to verify you are optimising your API requests!
April 8, 2026.
March 18, 2026. The new sonograms combine spectrograms and oscillograms in a single image, so separating these in two sections became redundant.
The following has been changed since API v2: