Developers

The World Music Atlas is open to build on: every place, its coordinates and its song's metadata as JSON and GeoJSON, a player you can embed in your own maps, lessons and exhibits, and a JavaScript package that wraps it all.

What you get — and what you don't

• Places: name, ISO code, kind, UN M49 continent and region, a representative point, and whether it is disputed.
• Songs: title, description, musical style, edition, curator's selection, the place's page and its embed player.
• No audio files or downloadable audio links, and no provider identifiers. Songs are heard through the embed player.
• No internal database ids. Places are identified by their slug; editions by theirs.

Endpoints

Base URL https://openmusicatlas.org. Responses are JSON, cached for an hour, and callable from any website (CORS). Each caller is limited to 300 requests every 10 minutes; please cache on your side.

Example: /api/v1/places/jamaica

{
  "place": {
    "slug": "jamaica",
    "name": "Jamaica",
    "isoCode": "JM",
    "kind": "country",
    "continent": "Americas",
    "region": "Caribbean",
    "coordinates": [
      -77.32,
      18.14
    ],
    "isDisputed": false,
    "pageUrl": "https://openmusicatlas.org/place/jamaica"
  },
  "entries": [
    {
      "edition": {
        "slug": "2026-founding",
        "name": "World Music Atlas — 2026 Founding Edition",
        "year": 2026,
        "version": 1,
        "frozenAt": "2026-09-13T23:36:12.857Z"
      },
      "entry": {
        "title": "Island of One People",
        "description": null,
        "style": null,
        "curatorsSelection": false,
        "pageUrl": "https://openmusicatlas.org/place/jamaica",
        "embedUrl": "https://openmusicatlas.org/embed/jamaica/2026-founding"
      }
    }
  ]
}

From JavaScript

The official package, @openverb/music-atlas, is a thin, typed wrapper around this API. It has no dependencies, works in Node 18+, browsers, Deno and Bun, and supports both import and require. The source is on GitHub.

npm install @openverb/music-atlas

import { atlas } from "@openverb/music-atlas"

const jamaica = await atlas.find("Jamaica")      // by name, ISO code or slug
const { entries } = await atlas.place(jamaica)
console.log(entries[0].entry.title)               // "Island of One People"

const caribbean = await atlas.places({ region: "Caribbean" })
const geojson = await atlas.geojson()            // the Founding Edition, ready for Leaflet or MapLibre
const player = atlas.embedHtml("jamaica")         // the player, as an <iframe>

GeoJSON on a map

One point feature per place, with the place and song metadata as properties. It loads directly into Leaflet, MapLibre, Mapbox, OpenLayers or QGIS. This is a complete page — save it as an HTML file and open it: every place becomes a marker, and each popup plays that place's song.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>World Music Atlas on a Leaflet map</title>
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <style>html, body, #map { height: 100%; margin: 0 }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    const map = L.map("map").setView([20, 0], 2)
    L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
      attribution: "&copy; OpenStreetMap contributors",
    }).addTo(map)

    fetch("https://openmusicatlas.org/api/v1/editions/2026-founding.geojson")
      .then((res) => res.json())
      .then((atlas) => {
        L.geoJSON(atlas, {
          onEachFeature: (feature, layer) => {
            const p = feature.properties
            layer.bindPopup(
              `<b>${p.name}</b><br>${p.title}<br>` +
              `<iframe src="${p.embedUrl}" width="300" height="212" style="border:0"></iframe>`,
              { maxWidth: 320 }
            )
          },
        }).addTo(map)
      })
  </script>
</body>
</html>

From Python

The same data with nothing but the standard library — for notebooks, GIS scripts and research.

import json
import urllib.request

url = "https://openmusicatlas.org/api/v1/editions/2026-founding.geojson"
with urllib.request.urlopen(url) as response:
    atlas = json.load(response)

print(atlas["name"], "-", len(atlas["features"]), "places")
for feature in atlas["features"][:5]:
    p = feature["properties"]
    lon, lat = feature["geometry"]["coordinates"]
    print(f"{p['name']}: {p['title']} ({lat}, {lon}) {p['pageUrl']}")

Embed the player

Any website may embed the player. It plays the song, links back to the place on Open Music Atlas, and runs in its own protected frame. Every place and edition has one; the embedUrl field gives its address.

<iframe
  src="https://openmusicatlas.org/embed/jamaica/2026-founding"
  width="100%" height="212" loading="lazy"
  style="border:0; border-radius:12px"
  allow="autoplay; encrypted-media"
  title="Jamaica — World Music Atlas"></iframe>

For AI agents

The package also describes the atlas as an OpenVerb verb library, openverb.music_atlas: the actions an AI agent may take with the atlas, every one of them read-only. Give the library to a model as its list of tools, and the executor carries out what it asks for. This part needs the openverb package alongside; the rest of the SDK doesn't.

npm install @openverb/music-atlas openverb

import { createMusicAtlasExecutor } from "@openverb/music-atlas/openverb"

const executor = createMusicAtlasExecutor()

await executor.execute({ verb: "get_place_song", params: { place: "Jamaica" } })
// { verb: "get_place_song", status: "success",
//   data: { place: {...}, edition: {...}, entry: { title: "Island of One People", ... } } }

A second collection: the Solar System

The atlas holds more than one collection. Beside the 203 places of the World Music Atlas sit the 30 bodies of the Solar System: the Sun, the planets, their great moons, the dwarf planets, the belts beyond, a comet and one spacecraft. Each body carries the established astronomy its song was written from, in a facts array, so an application can show what is fact and what is interpretation.

curl https://openmusicatlas.org/api/v1/solar-system/europa

{
  "body": {
    "slug": "europa", "name": "Europa", "kind": "moon",
    "zone": "Outer System", "orbits": "Jupiter",
    "title": "An Ocean With a Lid",
    "facts": ["A salt-water ocean under a shell of ice", "…"],
    "takes": 1,
    "pageUrl": "https://openmusicatlas.org/solar-system/europa",
    "embedUrl": "https://openmusicatlas.org/embed/europa/solar-2026-founding"
  },
  "orbits": { "slug": "jupiter", "name": "Jupiter" },
  "satellites": [],
  "takes": []
}

Licensing

The data (place and song metadata) and the music are licensed separately. The music is not licensed for download or reuse. Terms for the metadata are being finalised; until they are published, please credit “World Music Atlas, openmusicatlas.org” and link back to the place pages.

Coming next

Version 1 of the API is a stable contract: fields may be added, but never removed or renamed, and the JavaScript package follows it. A Python package is planned as the same kind of thin wrapper; until then, the standard-library example above works in any script or notebook.

New layers — cities first — and future editions and collections will appear in the same API as they are published.