Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nordicsemi/bluetooth-numbers-database/llms.txt

Use this file to discover all available pages before exploring further.

All data files in the Bluetooth Numbers Database are plain JSON arrays hosted in the v1/ directory of the GitHub repository. They are served over HTTPS via GitHub’s raw content CDN and can be fetched directly at runtime from any platform that can make an HTTP request — mobile apps, firmware tools, Python scripts, Swift applications, or anything else — without installing a package manager or any JavaScript tooling.

​
Base URL

https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/
Append the filename to this base URL to get the full endpoint for each file.

​
Available Files

FileURLDescriptionApproximate Entry Count
company_ids.jsonLinkBluetooth SIG-assigned Company Identifiers~3,998 entries
service_uuids.jsonLinkGATT Service UUID definitions~126 entries
characteristic_uuids.jsonLinkGATT Characteristic UUID definitions~682 entries
descriptor_uuids.jsonLinkGATT Descriptor UUID definitions~18 entries
gap_appearance.jsonLinkGAP Appearance category definitions~52 categories

​
Fetching in JavaScript

const response = await fetch(
  'https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/company_ids.json'
);
const companies = await response.json();

// Resolve a company by numeric code
const nordic = companies.find(c => c.code === 89);
console.log(nordic.name); // 'Nordic Semiconductor ASA'

​
Fetching in Python

import requests

response = requests.get(
    'https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/service_uuids.json'
)
services = response.json()

heart_rate = next(s for s in services if s['uuid'] == '180D')
print(heart_rate['name'])  # 'Heart Rate'
print(heart_rate['identifier'])  # 'org.bluetooth.service.heart_rate'

​
Fetching in Swift

import Foundation

let url = URL(string: "https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/company_ids.json")!

struct Company: Decodable {
    let code: Int
    let name: String
}

let task = URLSession.shared.dataTask(with: url) { data, response, error in
    guard let data = data, error == nil else {
        print("Error fetching data:", error ?? "unknown error")
        return
    }
    do {
        let companies = try JSONDecoder().decode([Company].self, from: data)
        if let nordic = companies.first(where: { $0.code == 89 }) {
            print(nordic.name) // "Nordic Semiconductor ASA"
        }
    } catch {
        print("Decoding error:", error)
    }
}
task.resume()

​
Fetching in Kotlin

import java.net.URL
import org.json.JSONArray

fun fetchCompanies(): JSONArray {
    val url = URL(
        "https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/company_ids.json"
    )
    val json = url.readText()
    return JSONArray(json)
}

fun resolveCompany(code: Int): String? {
    val companies = fetchCompanies()
    for (i in 0 until companies.length()) {
        val company = companies.getJSONObject(i)
        if (company.getInt("code") == code) {
            return company.getString("name")
        }
    }
    return null
}

// Usage (call from a coroutine or background thread)
println(resolveCompany(89)) // "Nordic Semiconductor ASA"

​
Caching Recommendations

The Bluetooth Numbers Database is updated periodically as new Company IDs and GATT attributes are registered with the Bluetooth SIG. However, it is not a real-time feed — updates happen on an irregular schedule, typically ranging from weeks to months between significant additions. Recommended caching strategy:
  • Fetch once at app startup and cache the data in memory for the lifetime of the process.
  • Persist to local storage (file system, SQLite, shared preferences) and refresh periodically — a daily or weekly refresh is more than sufficient.
  • Do not fetch on every BLE event. Fetching the full company_ids.json (~3,998 entries) on every scan result will add unnecessary latency and bandwidth overhead.
  • Pin to a specific commit or tag for production builds where reproducibility is critical (see the Info callout below).
For production apps, consider pinning to a specific commit SHA or git tag rather than master to avoid unexpected data changes. Replace master in the base URL with a full commit hash:
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/<commit-sha>/v1/company_ids.json
This guarantees that your app always fetches the exact dataset it was tested against, regardless of upstream changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us