Skip to main content API Wrapper

Project description

xeno-canto API Wrapper

xeno-canto-py is an API wrapper designed to help users easily download recordings and associated information.

Originally created to aid in data collection and filtering for the training of machine learning models.


Navigate to your desired file location in a terminal and then clone the repository with the following command:

git clone

The only file required for operation is the file, so feel free to remove the others or move to another working directory.

You may also use the package manager pip to install xeno-canto-py to include in your Python projects.

pip install xeno-canto

Then import the module:

import xenocanto

Or use it straight from the command line:

xeno-canto -dl Bearded Bellbird


Commands through the terminal are given in the following format:

-m 	[filters]	Metadata generation

-dl 	[filters] 	Download recordings

-d 	[filters]	Delete recordings

-p 	[num] 		Purge folders containing num or fewer recordings

-g 	[path] 		Generate metadata for provided library path (defaults to 'dataset/audio/')

filters are given in tag:value form in accordance with the API search guidelines. For help in building search terms, consult the xeno-canto API guide. The only exception is when providing English bird names as an argument to the -d command, which must be preceded with en: and have all spaces be replaced with underscores.

Examples of command usage are given below:

# Retrieving metadata
xeno-canto -m Bearded Bellbird q:A

# Downloading recordings
xeno-canto -dl Bearded Bellbird cnt:Brazil

# Delete recordings with ANY of specified criteria from
# library
xeno-canto -d q:D cnt:Brazil

# Purge folders with less than 10 recordings
xeno-canto -p 10

# Generate metadata for all recordings in the path
# (defaults to 'dataset/audio/')
xeno-canto -g


All pull requests are welcome! If any issues are found, please do not hesitate to bring them to my attention.


Thank you to the team at and all its contributors for putting together such an amazing database.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xeno-canto-2.0.2.tar.gz (7.3 kB view hashes)

Uploaded source

Built Distribution

xeno_canto-2.0.2-py3-none-any.whl (6.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page