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

  1. Use the daily export, not the API. Everything is published once a day as static files on our CDN.
  2. Start at the manifest: https://cdn.aws.bmlt.app/aggregator/manifest.json lists every file with its size, checksum and record count.
  3. Poll it with If-None-Match. A file whose data has not changed keeps its ETag and answers 304, so you only download what actually changed.
  4. The format matches the API. Each line is exactly what a GetSearchResults call returns, so code written against the API reads the export unchanged.
  5. 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/:

FileWhat it holds
manifest.jsonstart here: every file with its size, checksum and record count
meetings.ndjson.gzevery current meeting, one JSON object per line
meetings/root-<id>.ndjson.gzthe same, one file per root server
formats.json.gzformats
service_bodies.json.gzservice bodies
root_servers.jsonroot servers, with lastSuccessfulImport
curl -s https://cdn.aws.bmlt.app/aggregator/meetings.ndjson.gz | gunzip | head -1

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.