Reachout API v1

A free, read-only web service for recovery-meeting data from every fellowship, compiled by Reachout from public meeting lists.

Basics

Keys and limits

No key is needed: without one you may make 60 requests a minute from one address. For a site or app that needs more, get a free key (600 requests a minute): sign in to Reachout at reachout.kurtrasmussen.com/account (just an email address and a code) and press Get an API key. Send it as the header X-Api-Key: your-key (or ?api_key= when a header isn't possible). Over the limit you get 429 with Retry-After: 60.

Endpoints

GET /api/v1/meetings/near

In-person and hybrid meetings near a point, nearest first.

ParameterWhat it is
lat requiredLatitude of the point.
lng requiredLongitude of the point.
radius_kmSearch radius in kilometres (1-200). Default 40. Or use radius_miles (1-125).
fellowshipFellowship code(s), comma-separated (AA, NA, AL-ANON, ...; see /fellowships). Default: all.
dayWeekday(s), comma-separated: 0 = Sunday ... 6 = Saturday. Default: all.
attendancein_person and/or hybrid. Default: both.
min_scoreLowest secular score (0-5) to include. 3 = secular-friendly, 5 = listed as secular. Default 0.
limitHow many to return (1-500). Default 100.

Example: /meetings/near?lat=44.95&lng=-93.09&radius_km=10&fellowship=AA,NA&day=1&min_score=3

GET /api/v1/meetings

Meetings in one country (and optionally one state or province), page by page.

ParameterWhat it is
country requiredTwo-letter country code (US, CA, DE, ...).
regionState or province code within the country (MN, ON, ...). Default: the whole country.
fellowshipFellowship code(s), comma-separated (AA, NA, AL-ANON, ...; see /fellowships). Default: all.
dayWeekday(s), comma-separated: 0 = Sunday ... 6 = Saturday. Default: all.
attendancein_person, hybrid and/or online, comma-separated. Default: all.
min_scoreLowest secular score (0-5) to include. 3 = secular-friendly, 5 = listed as secular. Default 0.
limitHow many to return (1-1000). Default 500.
cursorFor the next page: the meta.next_cursor of the previous answer.

Example: /meetings?country=US&region=MN&fellowship=AA&limit=500

GET /api/v1/meetings/{id}

One meeting by its Reachout id (reachout_id). A copy listed by a second source returns the preferred copy.

ParameterWhat it is
id requiredThe meeting's reachout_id.

Example: /meetings/123456

GET /api/v1/online

Online meetings (and hybrid ones, which can be joined online), page by page.

ParameterWhat it is
fellowshipFellowship code(s), comma-separated (AA, NA, AL-ANON, ...; see /fellowships). Default: all.
dayWeekday(s), comma-separated: 0 = Sunday ... 6 = Saturday. Default: all.
include_hybrid1 to include hybrid meetings. Default 1.
min_scoreLowest secular score (0-5) to include. 3 = secular-friendly, 5 = listed as secular. Default 0.
limitHow many to return (1-1000). Default 500.
cursorFor the next page: the meta.next_cursor of the previous answer.

Example: /online?fellowship=SLAA&day=3

GET /api/v1/download

The whole data set as one zip, rebuilt weekly: README.txt, meetings.json (the same meeting shape as this API) and CSV tables of meetings, places, groups, clubhouses, fellowships and sources. About 50 MB. Needs an API key; at most 5 downloads a day per key.

ParameterWhat it is
api_keyYour key (or send it as the X-Api-Key header). Required here.

Example: /download?api_key=YOUR_KEY

GET /api/v1/fellowships

The fellowship codes Reachout uses, with names and websites.

Example: /fellowships

GET /api/v1/sources

The public lists Reachout reads, with links and when each was last read.

ParameterWhat it is
fellowshipFellowship code(s), comma-separated (AA, NA, AL-ANON, ...; see /fellowships). Default: all.
countryTwo-letter country code. Default: all.

Example: /sources?country=CA

The meeting object

The same shape as meetings.json in the weekly download: the Meeting Guide / 12 Step Meeting List fields, so tools that read that format read these meetings, plus Reachout's extras. Fields with no value are left out.

FieldWhat it is
reachout_idReachout's id for the meeting (use it with /meetings/{id}).
nameThe meeting's name.
day0 = Sunday ... 6 = Saturday.
time, end_timeLocal start and end time, 24-hour HH:MM (end_time may be missing).
timezoneIANA time zone, e.g. America/Chicago.
attendance_optionin_person, hybrid or online.
typesMeeting Guide type codes: O open, C closed, W women, M men, B Big Book, ST step study, SP speaker, and so on.
notesNotes from the list.
conference_url, conference_url_notes, conference_phoneHow to join online (online and hybrid meetings).
location, location_notes, formatted_address, address, city, state, postal_code, countryWhere it meets.
latitude, longitude, approximateMap point. approximate = "yes" when the point is a town centre, not the building.
groupThe group's name, when the list gives one.
urlThe page where the meeting is listed. Contact details are there, not here.
updatedWhen Reachout last saw the meeting on its list.
fellowshipFellowship code (see /fellowships).
secular_score0-5: how secular-friendly the meeting appears from its name, notes, types and list. 5 listed as secular, 3-4 secular-friendly signs, 2 no signal, 0-1 strongly religious format. An estimate by software, not a statement by the group.
source, source_idThe list it came from (see /sources).
location_id, group_id, venue_idReachout's ids for the place, group and clubhouse (as in the weekly download's CSV files).

Search results from /meetings/near also have distance_km and distance_miles.

Example

fetch("https://reachout.kurtrasmussen.com/api/v1/meetings/near?lat=44.95&lng=-93.09&radius_km=10&min_score=3")
  .then((r) => r.json())
  .then(({ data }) => data.forEach((m) => console.log(m.name, m.day, m.time, m.distance_km)));

Use it from an AI assistant (MCP)

Reachout is also an MCP server, so AI assistants can look up meetings on the spot, for example while helping you build a page. Add https://reachout.kurtrasmussen.com/mcp to Claude, ChatGPT, Cursor, VS Code or any MCP client as a custom connector (a remote MCP server). No sign-in or key is needed; a key, sent as the X-Api-Key or Authorization: Bearer header, gives a higher rate.

Tools: find_meetings_near, list_meetings_in_area, find_online_meetings, get_meeting, list_fellowships, list_sources, and website_code, which writes ready-to-paste code for a web page that shows meetings near a place, live from this API, with the credit badge. Each tool answers with the same meeting shape as the API.

Credit badge

When you show Reachout's meetings on a site or in an app, please show this credit, linked back to Reachout, and keep each meeting's url as a link to its source list:

Meeting data from Reachout

<a href="https://reachout.kurtrasmussen.com/" title="Recovery meetings of every fellowship, from Reachout"><img src="https://reachout.kurtrasmussen.com/badge.svg" alt="Meeting data from Reachout" width="170" height="22"></a>

Or as text: Meeting data from Reachout

Meeting data from <a href="https://reachout.kurtrasmussen.com/">Reachout</a>

Contact

Questions about the API or Reachout: info@kurtrasmussen.com. Corrections to a meeting belong with the list that publishes it (each meeting's url).

Terms of use

Free to use. Credit Reachout and the original lists; send corrections to the original lists (each meeting's url). Don't present the data as your own or imply endorsement by any fellowship. Meeting details change; check the source before relying on them.

Compiled by Reachout (https://reachout.kurtrasmussen.com) from public meeting lists. Please credit Reachout and the original lists, and send corrections to the original lists.

The whole data set is also available as a weekly download (with a key): https://reachout.kurtrasmussen.com/api/v1/download. A machine-readable description of this API: openapi.json.