Using the BMLT aggregator responsibly
The BMLT aggregator collects the meeting lists of every participating Narcotics Anonymous BMLT root server into one dataset, so an app, a website or a directory can use meeting data from anywhere in one place. It is free to use, needs no key, and is run by volunteers on a small budget.
This guide is for anyone who pulls that data: app developers, website owners, and people building meeting directories. The rule is simple: get the data from the daily export on our CDN, not from the live API. The live API is there to answer the person searching for a meeting right now; copying data through it slows that down for everyone. The export gives you the same data, costs the service nothing, and is easier for you.
Questions, or a use the export does not cover: admin@bmlt.app. We would much rather help you get the data efficiently than block anyone.
For the terms this data comes under — who may use the live API, and the conditions on reusing it — see the terms of use: https://cdn.aws.bmlt.app/aggregator/tos.html.
The short version
- Use the daily export, not the API. Everything is published once a day as static files on our CDN.
- Start at the manifest:
https://cdn.aws.bmlt.app/aggregator/manifest.jsonlists every file with its size, checksum and record count. - Poll it with
If-None-Match. A file whose data has not changed keeps itsETagand answers304, so you only download what actually changed. - The format matches the API. Each line is exactly what a
GetSearchResultscall returns, so code written against the API reads the export unchanged. - Need something the export does not cover? Email admin@bmlt.app before building anything.
The daily export
Everything is under https://cdn.aws.bmlt.app/aggregator/:
| File | What it holds |
|---|---|
manifest.json | start here: every file with its size, checksum and record count |
meetings.ndjson.gz | every current meeting, one JSON object per line |
meetings/root-<id>.ndjson.gz | the same, one file per root server |
formats.json.gz | formats |
service_bodies.json.gz | service bodies |
root_servers.json | root servers, with lastSuccessfulImport |
curl -s https://cdn.aws.bmlt.app/aggregator/meetings.ndjson.gz | gunzip | head -1
- About 35,000 meetings in about 4 MB, regenerated once a day around 05:20 UTC. The underlying data is imported from the root servers about every 4 hours, so a daily copy keeps what you show people accurate.
- Each line has exactly the fields
GetSearchResultsreturns, so code written against the API reads it unchanged. - It is served from a CDN, not from the aggregator, so downloading it costs the service nothing. Poll it as often as you like with
If-None-Match: a file whose data did not change keeps itsETagand answers304with no body. manifest.jsonlists every file with its size, SHA-256 and record count, and each root server's last successful import, so you can fetch only the root servers that changed.- Stale root servers are left out of
meetings.ndjson.gz. If the aggregator has not managed to import a root server for more than 14 days it only holds an old copy, and publishing that as current would send people to meetings that may not exist. Those servers are listed understale_root_serversin the manifest and still have their ownroot-<id>file if you want them knowingly. - Check
schema_versionin the manifest; it changes if the layout ever does.
Please do not crawl the API
The live API (https://aggregator.bmltenabled.org/main_server/) is there to serve people searching for a meeting, not to hand out copies of the whole dataset. Crawling it to build or refresh your own database competes with those searches, and it is what overloaded the service in the past: a handful of bulk copiers used more capacity than every app and website combined. The export exists so you never need to.
So, as an external consumer, take your data from the export above and do not pull it from the API. If the export genuinely does not fit your needs — for example you need data fresher than once a day — write to admin@bmlt.app before building anything, and we will work out a way to get you what you need.
If you get blocked
A 403 from the aggregator with a message addressed to your client means it was pulling from the API and using a large share of the server, and we had no other way to reach you. Email admin@bmlt.app: the block is lifted as soon as we have talked, and we will point you at the export so it does not happen again.
Thank you for building something that helps people find a meeting.