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.
In this guide you will install the bluetooth-numbers-database npm package, import its data collections, and perform lookups for Company IDs, Service UUIDs, and Characteristic UUIDs using standard JavaScript array methods. No build step, no configuration — just plain arrays ready to query.
The five data collections (companies, services, characteristics, descriptors, appearances) are plain JavaScript arrays — use standard Array methods like .find(), .filter(), and .map() for lookups. The package also exports version (string) and schemas (object).
Install
Add the package to your project using your preferred package manager:npm install bluetooth-numbers-database
Import the data
The package uses CommonJS (require) syntax. Destructure the exports you need:const {
version,
companies,
services,
characteristics,
descriptors,
appearances,
schemas,
} = require('bluetooth-numbers-database');
Look up a Company ID
Each entry in the companies array has a numeric code and a name. Use .find() to resolve a Company ID — for example, code 89 is Nordic Semiconductor ASA:const company = companies.find(c => c.code === 89);
console.log(company);
// { code: 89, name: 'Nordic Semiconductor ASA' }
const intel = companies.find(c => c.name === 'Intel Corp.');
console.log(intel);
// { code: 2, name: 'Intel Corp.' }
Look up a Service UUID
Each entry in the services array has a uuid (uppercase hex string), name, identifier (reverse-dot notation), and source. UUID 180D is the Heart Rate service:const service = services.find(s => s.uuid === '180D');
console.log(service);
// {
// name: 'Heart Rate',
// identifier: 'org.bluetooth.service.heart_rate',
// uuid: '180D',
// source: 'gss'
// }
source:const gsServices = services.filter(s => s.source === 'gss');
console.log(`${gsServices.length} SIG-defined services found`);
Look up a Characteristic UUID
Characteristic entries follow the same shape as services. UUID 2A37 is the Heart Rate Measurement characteristic:const characteristic = characteristics.find(c => c.uuid === '2A37');
console.log(characteristic);
// {
// name: 'Heart Rate Measurement',
// identifier: 'org.bluetooth.characteristic.heart_rate_measurement',
// uuid: '2A37',
// source: 'gss'
// }
const hrService = services.find(s => s.uuid === '180D');
const hrMeasurement = characteristics.find(c => c.uuid === '2A37');
console.log(`Service : ${hrService.name}`); // Heart Rate
console.log(`Characteristic: ${hrMeasurement.name}`); // Heart Rate Measurement
Using raw JSON files directly
If you are working outside of a Node.js environment — for example in a Python script, a mobile app, or a browser without a bundler — you can fetch the JSON files directly from GitHub using their raw URLs:
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/company_ids.json
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/service_uuids.json
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/characteristic_uuids.json
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/descriptor_uuids.json
https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/gap_appearance.json
fetch example that resolves a Company ID at runtime:
const response = await fetch(
'https://raw.githubusercontent.com/NordicSemiconductor/bluetooth-numbers-database/master/v1/company_ids.json'
);
const companies = await response.json();
const company = companies.find(c => c.code === 89);
console.log(company.name); // Nordic Semiconductor ASA
Available exports
The following named exports are available from the bluetooth-numbers-database package:
| Export | Type | Description |
|---|
version | String | The package version string (e.g. "1.0.4"), derived from package.json |
companies | Array | All registered Bluetooth SIG Company Identifiers (3,998 entries), each with a numeric code and name |
services | Array | GATT Service UUIDs (126 entries), each with uuid, name, identifier, and source |
characteristics | Array | GATT Characteristic UUIDs (682 entries), each with uuid, name, identifier, and source |
descriptors | Array | GATT Descriptor UUIDs (18 entries, e.g. Client Characteristic Configuration 2902), same shape as services |
appearances | Array | GAP Appearance categories (52 categories) and sub-categories for identifying device type from advertisement data |
schemas | Object | JSON Schema definitions keyed by collection name (companies, services, characteristics, descriptors, appearances) |
