{ "openapi": "3.1.1", "info": { "title": "Soundscape Recording Search API", "version": "1.0.0", "summary": "Find real, freely licensed sound recordings by place, category and keywords.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://soundscaperecordingsearch.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Find real, freely licensed sound recordings by place, category and keywords.", "description": "Searches Wikimedia Commons for geotagged audio recordings — birdsong, rain, rivers, streets, machines, voices and field recordings — by region, map point, sound category and keywords. Every result carries its licence, author, attribution line, coordinates and links to the source page and file; only CC0, public-domain, CC BY and CC BY-SA recordings are listed unless you ask for the others.\n\nMethodology:\n- Builds a Wikimedia Commons search (CirrusSearch) for audio files: `filetype:audio`, a `nearcoord:` circle for the region or point, an OR-group of keywords for the category and your own words.\n- Asks the MediaWiki API for each file’s coordinates, file URL, MIME type, duration, Wikimedia’s MP3 transcode and the licence, author, credit, date, description and categories from the file page (extmetadata). Nothing is filled in or guessed.\n- Classifies the licence conservatively: only CC0, public domain, CC BY and CC BY-SA count as usable; NonCommercial, NoDerivatives, GFDL-only, Free Art and unknown licences are not usable for remixing.\n- Writes a TASL attribution line (title, author, licence with link, source) for every recording, and tags results with sound categories by keywords in the title, description and categories.\n- Caches region and world searches for 12 hours to keep the load on Wikimedia low; searches around a point are never cached, so no coordinates are kept on the server.\n\nLicence and author data come from the Commons file pages and can be incomplete or wrong; check the file page before publishing. Sound tags are a keyword guess. Recordings can be removed from Commons at any time.", "tags": [ "apps" ], "x-mcp-tool": "soundscape_recording_search", "x-owner-app": "soundscape", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoundscapeRecordingSearchInput" }, "examples": { "example1": { "summary": "Weather recordings anywhere in the world", "value": { "category": "weather", "region": "world", "limit": 12 } }, "example2": { "summary": "Everything within 300 km of Berlin", "value": { "region": "point", "lat": 52.52, "lon": 13.405, "radiusKm": 300, "limit": 15 } }, "example3": { "summary": "Wildlife sounds in Europe", "value": { "category": "wildlife", "region": "europe", "limit": 12 } }, "example4": { "summary": "Field recordings without music", "value": { "category": "ambience", "region": "world", "limit": 20 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoundscapeRecordingSearchResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "SoundscapeRecordingSearchInput": { "type": "object", "additionalProperties": false, "properties": { "query": { "title": "Search words", "description": "Optional plain words such as “rain forest” or “harbour”. Search operators are ignored.", "type": "string", "maxLength": 120, "default": "" }, "category": { "title": "Sound category", "type": "string", "enum": [ "any", "wildlife", "weather", "water", "city", "machines", "voices", "ambience" ], "default": "any" }, "region": { "title": "Region", "description": "“Whole world” lists only recordings with coordinates.", "type": "string", "enum": [ "world", "europe", "british-isles", "mediterranean", "africa", "middle-east", "south-asia", "east-asia", "southeast-asia", "oceania", "north-america", "central-america", "south-america", "arctic", "antarctica", "point", "anywhere" ], "default": "world" }, "lat": { "title": "Latitude (for “Around a point”)", "type": "number", "minimum": -90, "maximum": 90, "default": 52.52, "x-unit": "°" }, "lon": { "title": "Longitude (for “Around a point”)", "type": "number", "minimum": -180, "maximum": 180, "default": 13.405, "x-unit": "°" }, "radiusKm": { "title": "Radius (for “Around a point”)", "type": "number", "minimum": 1, "maximum": 20000, "default": 100, "x-unit": "km" }, "limit": { "title": "Results per page", "type": "number", "minimum": 1, "maximum": 50, "default": 20 }, "offset": { "title": "Skip the first results", "description": "Use the “next offset” of a previous search to get the next page.", "type": "number", "minimum": 0, "maximum": 950, "default": 0 }, "includeRestricted": { "title": "Also list recordings that cannot be remixed", "description": "They are marked and never usable in Soundscape Atlas scenes.", "type": "boolean", "default": false } }, "required": [] }, "SoundscapeRecordingSearchResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "source", "searchString", "apiUrl", "params", "count", "recordings", "skipped", "nextOffset" ], "properties": { "source": { "type": "string" }, "searchString": { "type": "string" }, "apiUrl": { "type": "string" }, "params": { "type": "object", "additionalProperties": false, "required": [ "query", "category", "region", "lat", "lon", "radiusKm", "limit", "offset", "includeRestricted" ], "properties": { "query": { "type": "string" }, "category": { "type": "string" }, "region": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "radiusKm": { "type": [ "number", "null" ] }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "includeRestricted": { "type": "boolean" } } }, "count": { "type": "integer" }, "recordings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "source", "title", "fileName", "pageUrl", "fileUrl", "mp3Url", "mime", "durationSeconds", "sizeBytes", "lat", "lon", "author", "authorUrl", "credit", "description", "date", "commonsCategories", "tags", "licence", "attribution" ], "properties": { "id": { "type": "string" }, "source": { "const": "wikimedia-commons" }, "title": { "type": "string" }, "fileName": { "type": "string" }, "pageUrl": { "type": "string" }, "fileUrl": { "type": "string" }, "mp3Url": { "type": "string" }, "mime": { "type": "string" }, "durationSeconds": { "type": [ "number", "null" ] }, "sizeBytes": { "type": [ "number", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "author": { "type": "string" }, "authorUrl": { "type": "string" }, "credit": { "type": "string" }, "description": { "type": "string" }, "date": { "type": "string" }, "commonsCategories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "enum": [ "wildlife", "weather", "water", "city", "machines", "voices", "ambience", "music" ] } }, "licence": { "type": "object", "additionalProperties": false, "required": [ "code", "name", "url", "family", "allowed", "attributionRequired", "shareAlike", "reason" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "family": { "enum": [ "cc0", "pd", "cc-by", "cc-by-sa", "restricted", "unknown" ] }, "allowed": { "type": "boolean" }, "attributionRequired": { "type": "boolean" }, "shareAlike": { "type": "boolean" }, "reason": { "type": "string" } } }, "attribution": { "type": "string" } } } }, "skipped": { "type": "object", "additionalProperties": false, "required": [ "licence", "music", "invalid" ], "properties": { "licence": { "type": "integer" }, "music": { "type": "integer" }, "invalid": { "type": "integer" } } }, "nextOffset": { "type": [ "integer", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }