Using the Meetup API

Core Concepts

The Meetup API provides a simple interface for accessing Meetup Group data you can use in your own applications & mashups. The API supports several industry standard formats and a host of criteria to narrow results by time, geography or topic.

The easiest way to get started is to get your API key and then familiarize yourself with how to make a request using curl, wget or your favorite URL fetching tool. We also provide libraries in Python & Javascript to get you started working with the data quickly.

The API is currently limited to the methods detailed below -- some actions aren't supported yet, but more will be added in future versions. Finally, the API is definitely a work in progress, as you experiment we'd love to hear your feedback and how you're using the service -- Get in touch.

Authentication

To use the Meetup API you'll need a valid API key. Luckily, that isn't hard. If you're already registered with Meetup -- you already have one here. If not you need to register to get one.

Making a request

The API is a set of core methods and a common request format. These are combined to form a URL that returns the information you want. Here's an example of an API call that lists moms groups near Williamsburg, Brooklyn.

http://api.meetup.com/groups1.xml2/?zip=11211&topic=moms3&order=members4&key=ABDE12456AB23244455
  1. groups -- the method you're calling, in this case a request for groups
  2. xml -- the format of the response. Each method has a list of supported formats
  3. args -- zip & topic limit the results by geography and area of interest
  4. order -- how to order the results, in this case by # of members. To reverse the sorting order, you include the parameter "desc=desc" or "desc=true".
  5. key -- your unique API key

In addition, you can specify these parameters for more control:

  1. page -- the page size (maximum number of results in each response) to use on the results
  2. offset -- the starting page for results to return. For example, when page = 10, specifying "offset=0" will bring back records 1-10, "offset=1" will bring records 11-20, etc.
  3. desc -- reverses the sorting order, when you include the parameter "desc=desc" or "desc=true".

Every request needs to specify a method and key -- if no format is specified it defaults to 'json'. Details on the formats, parameters and ordering accepted by each method are listed below.

In addition, requests about a specific group can identify the group with either a group_id, or a topic and groupnum. The group_id can be retrieved from the id field from requests to the "Groups" method (detailed below), and the topic and groupnum can be found in the URL for the meetup group - for example, the group with the URL at http://volunteerism.meetup.com/167/ can be accessed with the parameters topic=volunteerism&groupnum=167.

Formats

Each API method has multiple ways you can request the data be returned as. All methods support json, and this is the default format used when you don't explicitly supply one. The other formats are supported when it makes sense for the type of data being requested.

  • JSON JavaScript Object Notation. Learn more here.
  • XML A simple XML format with the exact same fields as the json response.
  • KML Keyhole markup language. Learn more here.
  • RSS RSS 2.0. Learn more here.
  • ATOM Learn more here.

Read Methods

Groups

URL: http://api.meetup.com/groups/
Formats: json, xml, rss, atom, kml

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • member_id A member id number, limits results set to only those groups that the member specified by this id is currently a member of (excludes private groups, unless the member_id is the same as that of the member making the request)
  • zip A valid US zip code, limits the returned groups to those within radius miles.
  • country, city, state A valid country code, city and for the US, State. limits the returned groups to those within radius miles.
  • lat, lon A valid latitude and longitude, limits the returned groups to those within radius miles
  • topic Only return groups in the specified topic(s) [one topic allowed]
  • id Only return groups with the specified ID's [separate ID numbers with commas]
  • topic, groupnum Return the group with this topic and number
  • group_urlname Return the group with this custom url path (e.g., the string "teaneck-archaeologists" would refer to the group located at http://www.meetup.com/teaneck-archaeologists)
  • radius Radius, in miles for geographic requests, default 25 -- maximum 100

Ordering:

  • ctime group creation time [newest first]
  • name the name of the group
  • location group location, country, state [if present], city
  • members number of members [largest first]

Examples:

Get a list of all groups near Williamsburg, Brooklyn ordered oldest first, in xml format.

http://api.meetup.com/groups.xml/?zip=11211&order=ctime&desc=true&key=ABDE12456AB2324445

List all the pug groups in Reno, Nevada return json.

http://api.meetup.com/groups.json/?&topic=pug&country=us&state=nv&city=reno&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • id The ID of the group
  • name The name of the group
  • link URL of the group's main page on meetup.com
  • updated The last date and time that the group was modified
  • members The number of members currently active in the group
  • created The date and time that this group was created
  • photo_url URL of the group photo
  • description A brief description of the group
  • lat, lon Latitude and longitude coordinates of group location
  • country, city, state Country, City, (and for the US, State) where this group is located
  • zip The zip code where this group is located
  • organizerProfileUrl A link to the group's organizer profile on meetup.com
  • daysleft If this group is in need of an organizer, number of days left until it expires (otherwise blank)

Events

URL: http://api.meetup.com/events/
Formats: json, xml, rss, atom, kml

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • zip A valid US zip code, limits the returned groups to those within radius miles.
  • country, city, state A valid country code, city and for the US, State. limits the returned groups to those within radius miles.
  • lat, lon A valid latitude and longitude, limits the returned groups to those within radius miles
  • topic Return events in the specified topic(s) [one topic allowed]
  • id Return events with the specified ID's [separate ID's keys with commas]
  • group_id Return events from groups with the specified ID's [separate ID's keys with commas]
  • topic, groupnum Return events for the group with given topic and number
  • group_urlname Return events for the group with this custom URL path
  • after Return events that start after the specified date, format MMDDYYYY (if the time range includes past events, you must specify an event id, group id, or groupnum and topic)
  • before Return events that started before the specified date, format MMDDYYYY (limited to one year beyond the after date, and if this includes past events you must specify an event id, group ud, or groupnum + topic)
  • radius Radius, in miles for geographic requests, default 25 -- maximum 100

Ordering:

  • time event time
  • group the name of the group having the event
  • topic the topic of the event
  • location group location, country, state [if present], city

Examples:

All upcoming events in New York, NY
http://api.meetup.com/events.json/?country=us&state=ny&city=new+york&key=ABDE12456AB2324445
Moms events in London
http://api.meetup.com/events.json/?country=gb&city=london&topic=moms&key=ABDE12456AB2324445
Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • id The ID of the event
  • name The name (title) of the event
  • updated The last date and time that the event's information was modified
  • time The date and time that the event will take place
  • photo_url URL of the event photo
  • lat, lon Latitude and longitude coordinates of group location
  • venue_lat, venue_lon If the event has a public venue chosen, the latitude and longitude of the venue (otherwise, these will be blank)
  • myrsvp The current RSVP status for this event of the user making the request (could be "yes","no","maybe", or "none")
  • event_url URL of the event's page on meetup.com
  • rsvpcount Current number of people who have rsvp'd "Yes" or "No" to this event.
  • ismeetup Set to either a "1" or a "0" if this is a Meetup event or just a calendar note, respectively
  • fee Fee for this event (or 0.0 if this event has no fee)
  • feecurrency Currency of the fee for this event
  • feedesc Fee description, or blank if this event has no fee
  • attendee_count Number of attendees at the event

Topics

URL: http://api.meetup.com/topics/
Formats: json, xml, rss, atom

Parameters:

  • topic Return topic (one topic only) with the specified key (found in the first part of the meetup group's URL, for example 'digcam' or 'classical')
  • name Return topics that match the specified name (e.g. 'Digital Photography', 'Classical Music')
  • search Return topics related to a list of search terms [separate search keywords with spaces]

Ordering:

  • topic the topic key
  • name the topic name
  • members total members in the topic
  • alertees total alertees in the topic

Examples:

Get a list of topics related to "Dogs"
http://api.meetup.com/topics.xml/?name=dog&key=ABDE12456AB2324445
Get a list of topics with the search keyword "election" in the description
http://api.meetup.com/topics.xml/?search=election&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • id The ID of the topic
  • name The name of the topic
  • description A description of the topic
  • link A URL of the topic's page on meetup.com
  • updated The last date and time that this topic's information changed
  • members The number of members who belong to groups under this topic
  • urlkey The unique keyword used to identify this topic

Cities

URL: http://api.meetup.com/cities/
Formats: json, xml

Parameters:

  • country Return cities in these countries [separate countries with commas]
  • state Return cities in these states [separate states with commas]

Ordering:

  • name the city name
  • members total members in the city

Examples:

Return all cities in New York.
http://api.meetup.com/cities.xml/?state=ny&key=ABDE12456AB2324445

Response Data

Each item in the results list will contain these fields:

  • city The name of the city
  • lat, lon The latitude and longitude of the city's location
  • country, state, zip The country that the city is in, plus state and zip for cities in the U.S.
  • members The number of members located in the city

Members

URL: http://api.meetup.com/members/
Formats: json, xml

Parameters: at least one of the required parameter(s) must be supplied with the request. If any of the groups you specify are private, you will not see its members listed in the result set unless you are a member of that group.

  • relation Supply the string "self" as the value for this parameter to get the information of the member linked to the API key making the request.
  • group_id Return members in groups with these ID numbers [separated by commas]
  • topic, groupnum Return members for the group with given topic and number
  • group_urlname Return members for the group with the given custom URL path

Ordering:

  • name the name of the member

Examples:

Return active members in group 176399
http://api.meetup.com/members.json/?group_id=176399&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • id The member's id
  • name The member's name
  • link URL to the member's profile page on meetup.com
  • bio A description of the member
  • lat, lon Latitude and longitude coordinates of the members reported city
  • country, city, state Country, City, (and for the US, State) the member has provided

Rsvps (read)

URL: http://api.meetup.com/rsvps/
Formats: json, xml, rss, atom

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • event_id Return members that RSVP'd to events with these ID numbers [separated by commas]

Ordering:

  • name the name of the attendee

Examples:

Return members who RSVP'd to event 437658
http://api.meetup.com/rsvps.json/?event_id=437658&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • name The member's name
  • link URL to the member's profile page on meetup.com
  • comment The message that the member provided when RSVP was made
  • lat, lon Latitude and longitude coordinates of the members reported city
  • country, city, state Country, City, (and for the US, State) the member has provided
  • answers Answers to event survey questions provided when the member RSVP'd
  • created, updated Timestamps indicating when the RSVP was first set and when it was last updated

Photos

URL: http://api.meetup.com/photos/
Formats: json, xml

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • group_id Return photos in groups with these ID numbers [separated by commas]
  • topic_id Return photos in topics with this ID number
  • topic Return photos in this topic
  • topic, groupnum return photos for the group with given topic and number
  • group_urlname return photos for the group with given custom URL path

Ordering:

  • photo_album_id the id of the photo, (newer = higher)

Examples:

Return public photos from the Moms topics.
http://api.meetup.com/photos.json/?topic=moms&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • albumtitle The name of the photo album that the photo belongs to
  • link URL where the photo can be viewed
  • member_url URL of the public profile of the member who posted the photo
  • descr A description of the photo
  • created The time and date that the photo was created

Comments

URL: http://api.meetup.com/comments/
Formats: json, xml, rss, atom

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • group_id Return comments in groups with these ID numbers [separated by commas]
  • topic, groupnum Return comments for the group with given topic and number
  • group_urlname Return comments for the group with this custom URL path
  • rating Only return comments rating the group this number or higher
  • review_only Only return comments with a text review [no ratings only comments]

Ordering:

  • ctime the date the comment was posted
  • rating the rating from the comment

Examples:

Return comments rated three and higher from the NY Tech Group.
http://api.meetup.com/comments.json/?topic=newtech&groupnum=1&rating=3&key=ABDE12456AB2324445

Response Data

Each item in the results list for a JSON or XML request will contain these fields:

  • name The name of the member that posted the comment
  • link Link to the members profile page
  • comment Text of the comment that was posted
  • rating The rating the member gave the group
  • descr A description of the photo
  • created The time and date that the photo was created
  • lat, lon Latitude and longitude coordinates of the members reported city
  • country, city, state Country, City, (and for the US, State) the member has provided

Write Methods

RSVP

URL: http://api.meetup.com/rsvp/
Formats: json, xml

Parameters: at least one of the required parameter(s) must be supplied with the request.

  • event_id The event that you are RSVP'ing to.
  • rsvp The RSVP setting - value must be either "yes". "no", or "maybe"
  • guests Number of guests also coming to the event.
  • comments A comment to post along with the RSVP
  • member_id Organizers only - Set RSVP on behalf of this member. If omitted, the RSVP is for the account that your API key is linked to (default behaviour)

Examples:

RSVP 'yes' to the event with id 7922414.
http://api.meetup.com/rsvp/?event_id=7922414&rsvp=yes&key=ABDE12456AB2324445

Response Data

For this method, response data will only consist of either a success or failure message. If the RSVP was successful, the success message will also contain the event_id of the event that was just RSVP'd to.

Callbacks

If you request json, and want to play with the API in a web browser -- callbacks are useful. Specifing a callback will allow you to populate sample data using a <script/> tag by returning javascript that calls the function you proide as a query parameter.

http://api.meetup.com/topics.json/?callback=gotIt&page=1&key=ABDE12456AB2324445
gotIt({"results":[...], "meta": {...}})

Responses

The context of a successful response to a query depends on the format it was requested in, though there are some broad similarities between the JSON and XML formats. Here's two samples:

  • JSON

    curl http://api.meetup.com/topics.json/?key=ABDE12456AB2324445\&page=1 
    {
   "results":[
      {
         "id":"4422",
         "updated":"Mon Jun 26 15:01:05 GMT 2006",
         "description":"Meet fellow Social Networkers near you! Come to a local Social Networking Meetup to make valuable social connections and cultivate relationships with other elbow-rubbers in your area.",
         "name":"Social Networking",
         "link":"http:\/\/socialnetwork.meetup.com\/",
         "urlkey":"socialnetwork",
         "members":"245701"
      }
   ],
   "meta":{
      "id":"",
      "title":"Meetup Topics",
      "count":1,
      "updated":"",
      "description":"API for accessing meetup topics",
      "next":"",
      "link":"http:\/\/127.0.0.1\/meetup_api\/topics\/",
      "method":"Topics",
      "total_count":3063,
      "url":"http:\/\/127.0.0.1\/meetup_api\/topics\/\/?order=members&key=1&page=1&format=json&desc=0&offset=0",
      "prev":""
   }
}

  • XML

    curl http://api.meetup.com/topics.xml/?key=ABDE12456AB2324445\&page=1 
    <?xml version='1.0' encoding='UTF-8'?>
<results>
  <head>
    <url>http://127.0.0.1/meetup_api/topics//?order=members&amp;key=1&amp;page=1&amp;format=xml&amp;desc=0&amp;offset=0</url>
    <link>http://127.0.0.1/meetup_api/topics/</link>
    <total_count>3063</total_count>
    <description>API for accessing meetup topics</description>
    <title>Meetup Topics</title>
    <count>1</count>
    <next/>
    <method>Topics</method>
    <id/>
    <updated/>
  </head>
  <items>
    <item>
      <updated>Mon Jun 26 15:01:05 GMT 2006</updated>
      <members>245701</members>
      <name>Social Networking</name>
      <link>http://socialnetwork.meetup.com/</link>
      <description>Meet fellow Social Networkers near you! Come to a local Social Networking Meetup to make valuable social connections and cultivate relationships with other elbow-rubbers in your area.</description>
      <urlkey>socialnetwork</urlkey>
      <id>4422</id>
    </item>
  </items>
</results>

The results section contains a list of the items that match the criteria you supplied. The meta section supplies information about the response.

  • count is the number of records returned
  • total count is the total number of records that match your criteria
  • updated is the last time one of the items in the request
  • title, description some descriptive information about the request
  • next if the total count is more than the count, this url will request the next set of records
  • url the url used to generate this request
  • method the API method called

RSS, ATOM and KML topics don't return the meta information provided by the XML & JSON formats, there's no real need for them to do so.

OAuth Support

The Meetup API also supports authentication of third-party applications using the OAuth protocol. This allows your application to access a user's data and RSVP to events on behalf of the user (after they have explicitly granted permission). If you would like to set up an OAuth consumer to use for your application, please email us. The procedure to making requests with OAuth is as follows:

  • Fetch a request token, by using the request token URL: http://www.meetup.com/oauth/request/. This request will return a key and secret for a request token.
  • Redirect the user to the authorization url http://www.meetup.com/authorize/?oauth_token=your_request_token_key. You may also optionally append an oauth_callback parameter, which will be the URL that a user is redirected to after they authorize the application.
  • Fetch an access token, by using the access token URL: http://www.meetup.com/oauth/access/. If the user has chosen to allow the application, the request will return an access token key and secret which can be used for subsequent requests.
  • Make API calls as normal - but with the necessary OAuth parameters added to the request. Meetup users can see a list of applications they've authorized in their account settings page, and choose to remove an application. After a user chooses to remove an application, the access token will expire and any requests made with the token will fail. The user will need to re-authorize the application in order to allow access to continue with a new token.

Signatures are used to ensure the identity of the consumer application. Currently, the Meetup implementation of OAuth supports plaintext and HMAC_SHA1 as signature methods. For the URL portion of the signature base string, use the following values:

  • Request Tokens: http://www.meetup.com/oauth/request/
  • Access Tokens: http://www.meetup.com/oauth/access/
  • Protected Resources (API calls): http://api.meetup.com/
For complete details on how to form signatures for OAuth requests, refer to the OAuth specification details.

OAuth requests must also satisfy the following requirements:

  • Include a timestamp (oauth_timestamp) which must match to within a 5 minute window of the server time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • Include a nonce (oauth_nonce) which is a unique, randomly generated number that is specific to this request.
  • Include the consumer key (oauth_consumer_key) which is used to identify the application making the request.
  • Include the signature method (oauth_signature_method) and signature (oauth_signature) which are cryptographically generated digests of the resource URL, the parameters, the consumer secret, and the nonce + timestamp values.
If any of these components are missing or invalid, the OAuth request will be rejected with an error. The tedious part of assembling these parameters is easily addressed by using one of the open source OAuth clients or the Meetup Python client, which has bundled support for OAuth requests. Here is an example of how to use the Python client to establish an OAuth session: 

>>> import meetup_api_client
First, create a client object specifying your applications consumer key and secret.
>>> mucli = meetup_api_client.MeetupOAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET)
Then, initialize a new oauth session:
>>> oauth_session = mucli.new_session()
Fetch a request token from the server.
>>> oauth_session.fetch_request_token()
oauth_token=6d6bbb78faffccb2b3900c9c728370fb&oauth_token_secret=6b632dbc6d1dba391b350d3c20df0b8a
Get the authorization URL for this token - your application must send the user
to this URL to authorize access before the process can proceed. Append your callback parameter here.
>>> oauth_session.get_authorize_url() 
'http://www.meetup.com/authorize/?oauth_token=6d6bbb78faffccb2b3900c9c728370fb'
Fetch access token. If the user chose to authorize the application, this should succeed.
>>> oauth_session.fetch_access_token()
Make calls as necessary. Use oauthreq=oauth_session as a keyword parameter for each request to use the token.
>>> mucli.get_members(relation="self", oauthreq=oauth_session)

You should store access tokens (key and secret) so that they can be re-used without forcing the user to authorize a new token every time. To initialize an OAuth session with an already existing access token, pass the key and secret as keyword params to the new session (then continue to make API calls as normal): 

>>> memberinfo = mucli.new_session(access_key=token_db.access_key, access_secret=token_db.access_secret)

Errors

When everything goes well, we'll send a 200 response code along with your data. If there was a problem, you will receive a response with error details formatted in either XML or JSON [depending on which format was requested] as well as a corresponding HTTP error code, as follows:

  • 401 Unauthorized when you don't provide a valid key
  • 400 BadRequest when there was a problem with the request
  • 404 NotFound if you request for a method that does not exist
  • 500 ServerError if we messed up [please let us know]

The 400 BadRequest response is something of a catch-all: sent if you have incorrect or missing parameters, if you exceed your API limits or you request an unsupported format. The actual response body will have more detail on what actually happened, formatted in JSON or XML [dependent on the original request format].

Limits

We currently limit you to 100 requests per hour, and 200 max results for each request. We can tweak these limits at an individual level, so if you think you need a higher limit, get in touch.

Support

Email us with any suggestions, questions or problems.