xc-api-py 0.1.16

An intuitive, type-safe Python wrapper for the Xeno-Canto API

Xeno Canto API Client for Python

An intuitive, type-safe Python wrapper for the Xeno-Canto API.
Streamline your bioacoustics and machine learning workflows by searching, filtering, and processing wildlife recordings with full validation and IDE autocompletion.

Project Sponsors

Disclaimer

This project is a free and open-source tool intended for educational purposes only;
This project is provided AS IS without any warranty - use at your own risk;
This project is not associated with, maintained by, or endorsed by the Xeno-Canto Foundation;
Users are responsible for adhering to the Xeno-Canto Terms of Use and respecting the licensing of individual recordings.

Quickstart

pip install xc-api-py

pdm add xc-api-py

Basic Usage

from xc_api import Client, SearchQuery, tags
from datetime import timedelta

# Instanciate a client with your Xeno Canto API key
client = Client('Your API key')

# Create a query
query = SearchQuery(
  animal_genus='acrocephalus',
  animal_sex='male',
  recording_length=tags.Length.at_least(timedelta(seconds=10)),
  recording_country=tags.Country('germany'),
)

# Search the API, optionally pass a limit argument
recordings = client.find(query, limit=10)

# Get a specific recording
recording = client.get_by_id('129150')

Advanced Usage

Pandas

from xc_api import SearchQuery, RecordingAudio
import pandas as pd

query = SearchQuery(...)
recordings = client.find(query)
df = pd.DataFrame.from_records([r.model_dump() for r in recordings])

SoundDevice

from xc_api import SearchQuery, RecordingAudio
import sounddevice as sd

recording = client.get_by_id(...)

audio = RecordingAudio.from_recording(recording)

with audio.load() as a:
  sd.play(a.to_numpy(), a.sample_rate)
  sd.wait()

# Optional: save original file locally
audio.save()

BirdNET

from xc_api import SearchQuery, RecordingAudio
from birdnetlib import RecordingBuffer
from birdnetlib.analyzer import Analyzer
from datetime import timedelta

analyzer = Analyzer()

query = SearchQuery(
  animal_group='birds',
  recording_sample_rate=tags.SampleRate(48000), # IMPORTANT: BirdNET analyzer expects 48000Khz
)

recording = client.find_one(query, limit=1)

audio = RecordingAudio.from_recording(recording)

with audio.load() as a:
  arr = a.to_birdnet(length=timedelta(seconds=3.0)) # Optional: Segment the audio

buffer = RecordingBuffer(analyzer, arr)
buffer.analyze()

for detection in buffer.detections:
  ...