{"id":19856366,"url":"https://github.com/joesiu/xeno-canto-api-ts","last_synced_at":"2026-04-09T23:46:04.610Z","repository":{"id":216250949,"uuid":"740127425","full_name":"JoeSiu/xeno-canto-api-ts","owner":"JoeSiu","description":"A TypeScript wrapper for the Xeno Canto API","archived":false,"fork":false,"pushed_at":"2024-04-23T17:52:30.000Z","size":458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-24T16:11:00.423Z","etag":null,"topics":["api","bird","birds","database","grasshopper","javascript","npm","npm-package","sound","typescript","wildlife","xeno-canto"],"latest_commit_sha":null,"homepage":"https://joesiu.github.io/xeno-canto-api-ts/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoeSiu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-07T15:57:42.000Z","updated_at":"2024-06-12T16:54:57.121Z","dependencies_parsed_at":"2024-06-12T16:54:50.159Z","dependency_job_id":"7bcf31c5-8d20-4839-b691-4468a1ff541c","html_url":"https://github.com/JoeSiu/xeno-canto-api-ts","commit_stats":{"total_commits":47,"total_committers":2,"mean_commits":23.5,"dds":"0.12765957446808507","last_synced_commit":"001a22468249d7bc7a65a9cb4b7ef5d54782e8ba"},"previous_names":["joesiu/xeno-canto-api-ts"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeSiu%2Fxeno-canto-api-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeSiu%2Fxeno-canto-api-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeSiu%2Fxeno-canto-api-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoeSiu%2Fxeno-canto-api-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoeSiu","download_url":"https://codeload.github.com/JoeSiu/xeno-canto-api-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240957902,"owners_count":19884828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bird","birds","database","grasshopper","javascript","npm","npm-package","sound","typescript","wildlife","xeno-canto"],"created_at":"2024-11-12T14:15:20.990Z","updated_at":"2026-04-09T23:46:04.604Z","avatar_url":"https://github.com/JoeSiu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xeno Canto API\n\n\u003e A TypeScript wrapper for the [Xeno Canto](https://xeno-canto.org/) API with no dependencies.\n\n[![NPM Version](https://img.shields.io/npm/v/xeno-canto-api-ts)](https://www.npmjs.com/package/xeno-canto-api-ts) [![GitHub Release](https://img.shields.io/github/v/release/JoeSiu/xeno-canto-api-ts)](https://github.com/JoeSiu/xeno-canto-api-ts/releases/latest) [![npm bundle size](https://img.shields.io/bundlephobia/min/xeno-canto-api-ts)](https://www.npmjs.com/package/xeno-canto-api-ts) [![MIT License](https://img.shields.io/badge/license-GPL-blue)](https://github.com/JoeSiu/xeno-canto-api-ts/blob/main/LICENSE) [![Build Status](https://github.com/JoeSiu/xeno-canto-api-ts/actions/workflows/ci.yaml/badge.svg)](https://github.com/JoeSiu/xeno-canto-api-ts/actions/workflows/ci.yaml) [![GitHub Repo stars](https://img.shields.io/github/stars/JoeSiu/xeno-canto-api-ts)](https://github.com/JoeSiu/xeno-canto-api-ts)\n\n## Introduction\n\nA Node.js implementation with TypeScript support for the [xeno-canto.org](https://xeno-canto.org) API 3.0. It provides an easy way to search for various bird and wildlife sound recordings.\n\n## Install\n\nTo install, run the following command in your terminal:\n\n```bash\nnpm install xeno-canto-api-ts\n```\n\n## Usage\n\n**Note: An API Key is required for Xeno-Canto API v3. You can obtain one by visiting your [Account Page](https://xeno-canto.org/account).**\n\n### Import\n\nTo use `xeno-canto-api-ts` in your Node.js project, you need to import it as follows:\n\n```ts\nimport * as XenoCanto from \"xeno-canto-api-ts\";\n```\n\n### Simple Search\n\nYou can pass a filter option (e.g., English name) to the `search` method like this:\n\n```ts\nconst result = await XenoCanto.search({\n  key: \"{YOUR_API_KEY}\"\n  en: \"Owl\",\n});\n// Do something with result\n```\n\nor\n\n```ts\nXenoCanto.search({\n  key: \"{YOUR_API_KEY}\"\n  en: \"Owl\",\n}).then((result) =\u003e {\n  // Do something with result\n});\n```\n\nIf the search is successful, the `search` method will return an object with the following properties:\n\n- `url`: The query URL used for the search\n- `rawResponse`: The original Response object from the fetch\n- `xrResponse`: An `XCResponse` object that contains the fetched data\n\nYou can access the data like this:\n\n```ts\nconsole.log(result.rawResponse.status); //Response status code, e.g., 200\nconsole.log(result.xcResponse.numRecordings); // Total number of recordings\nconsole.log(result.xcResponse.recordings[0].file); // The first recording result's sound file download URL\n```\n\n### Advanced Search\n\nYou can pass a `XCQueryOption` object to the `search` method like this:\n\n```ts\n// Create options\nconst options: XenoCanto.XCQueryOption = {\n  key: \"{YOUR_API_KEY}\", // Required\n  en: \"Eagle\", // Search by English name\n  grp: \"birds\", // Optional\n  cnt: \"United States\", // Optional\n  // ...\n};\n\nconst result = await XenoCanto.search(options);\n```\n\n- Some of the `XCQueryOption` properties accepts operators such as `=`, `\u003e`, `\u003c` or `-`. For example, the recording length property `len` can accept `10`, `\"\u003e120\"` or `\"=19.8\"`.\n- The options list can accept additional properties that are not specified in the current API documentation in case of future updates. Note that the API will disregard any non-existing query parmeters.\n\n#### Multiple Pages\n\nFor results that have multiple pages, you can pass the `page` parameter to the `search` method:\n\n```ts\n// Create options\nconst options: XenoCanto.XCQueryOption = {\n  key: \"{YOUR_API_KEY}\",\n  en: \"Eagle\",\n  grp: \"birds\",\n  cnt: \"United States\",\n};\n\n// Initial search to get total pages\nconsole.log(\"Fetching page 1...\");\nconst initialResult = await XenoCanto.search(options);\nconst totalPages = initialResult.xcResponse.numPages;\n\nconsole.log(initialResult.xcResponse.recordings[0]);\n\n// Fetch remaining pages if any\nif (totalPages \u003e 1) {\n  for (let i = 2; i \u003c= totalPages; i++) {\n    console.log(`Fetching page ${i}/${totalPages}...`);\n    \n    // Pass updated page number while keeping other options\n    const result = await XenoCanto.search({ ...options, page: i });\n    console.log(result.xcResponse.recordings[0]);\n\n    // Rate limit precaution\n    await new Promise((resolve) =\u003e setTimeout(resolve, 1000));\n  }\n}\n```\n\n### Additional Options\n\nThe wrapper also provides additional options by passing a `AdditionalSearchOption` object to the `search` method\n\n#### Change API Base URL\n\nFor development purpose, the Base URL can be changed as follows:\n\n```ts\n// Create options\nconst options: XenoCanto.XCQueryOption = {\n  key: \"{YOUR_API_KEY}\",\n  en: \"Owl\",\n};\nconst additionalOptions: XenoCanto.AdditionalSearchOption = {\n  baseUrl: \"https://run.mocky.io/v3/9f08db9a-cfba-4b1d-8c4a-765932f6cf3b\", // A custom URL that will return a example JSON data\n};\n\nconst result = await XenoCanto.search(options, additionalOptions);\n```\n\n### Other Usages\n\n#### Custom Data Fetching\n\nIf you wish to implement your own data retrieval methods instead of using the default Fetch API, you can utilize the `constructQueryUrl` and `convertJsonToXCResponse` methods:\n\n```ts\nconst options: XenoCanto.XCQueryOption = {\n  key: \"{YOUR_API_KEY}\",\n  en: \"Owl\",\n};\nconst customUrl = XenoCanto.constructQueryUrl(\"/custom-endpoint/\", options); // This will returns string `/custom-endpoint/?key=\"{YOUR_API_KEY}\"\u0026query=en:\"Owl\"`\n// Your implementation to retrieve the JSON data...\nconst xcResponse = XenoCanto.convertJsonToXCResponse(json); // If the JSON format is correct, this will convert it to type `XCResponse` which has type hinting\n```\n\n#### Query Parameters / Response's Key Names\n\nTo get the query parameters names / response JSON key names of the Xeno Canto API, you can use the `XCQueryNameDefinition`, `XCResponseNameDefinition` and `XCRecordingNameDefinition` enum, for example, `XCQueryNameDefinition.rec`will return the string `rec`.\n\n## Limitation\n\nDue to the API limitation, only English queries are supported, and the query should based on scientific or common names. You may refer to the [IOC World Bird List - Multilingual Version](https://www.worldbirdnames.org/new/ioc-lists/master-list-2/) for looking up and mapping the corresponding names.\n\n## Resources\n\nPlease refer to the [documentation](https://joesiu.github.io/xeno-canto-api-ts/) for details and API references.\n\nTo learn more about the Xeno Canto's query parmeters, see [https://xeno-canto.org/explore/api](https://xeno-canto.org/explore/api) and [https://xeno-canto.org/help/search](https://xeno-canto.org/help/search).\n\nTo build this package from source, please refer to the [wiki](https://github.com/JoeSiu/xeno-canto-api-ts/wiki) page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoesiu%2Fxeno-canto-api-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoesiu%2Fxeno-canto-api-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoesiu%2Fxeno-canto-api-ts/lists"}