Meet the API

The Meetup API provides simple RESTful HTTP and streaming interfaces for exploring and interacting Meetup platform from your own apps.

Composing 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 parenting groups near Williamsburg, Brooklyn.

https://api.meetup.com1/find/groups2?zip=11211&radius;=1&category=253&order=members4

1. api.meetup.com -- the API host, in this case for the REST API, for the stream API use stream.meetup.com
2. /find/groups -- the method you're calling, represented as a path
3. args -- zip, radius, & category 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".

Most requests must be authenticated. Unless otherwise specified, response payloads are returned in JSON format.

Cross Origin Resource Sharing ¶

The Meetup API supports the CORS specification which allows browser clients hosted on a domain other than api.meetup.com to communicate directly with the API.

The API uses OAuth consumer redirect uris to validate a request's origin, so you must be using OAuth to benefit from CORS. The suggested OAuth authorization scheme is the OAuth2 Implicit flow, which is tailored for browsers. Once a browser client receives authorization and issues an HTTP request, the Meetup API will validate the request's Origin header with the consumers registered redirect URI in addition to the HTTP method used for the given API endpoint.

You can inspect which HTTP methods an API method supports issuing an OPTIONS request for the given method uri and origin. An example of the response headers is below.

curl -i \
  -X OPTIONS \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Origin: http://consumerhost.com' \
  'https://api.meetup.com/members/self'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: X-Meetup-server, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimt-Reset
Access-Control-Allow-Origin: http://consumerhost.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Max-Age: 86400
         

You can find the current browser support here here.

Responses ¶

• JSON

  The current version of the API, v3, serializes all responses as JSON. Relevant metadata is encoded has HTTP headers with the response.

  Paginating information of collection-oriented data is provided via Link headers. Link types will be annotated with a "rel" attribute.

  $ curl -H "Authorization: Bearer {access_token}" -i "https://api.meetup.com/find/groups?zip=10021"
  
  HTTP/1.1 200 OK
  ...
  Link: <https://api.meetup.com/find/groups?zip=10021&page;=200&offset;=1>; rel="next"
  X-Total-Count: 10171
  ...
  
  [{...}]
  

  Some fields of response objects may not contain values, either based on privacy or availability. In these cases, the Meetup API will omit these fields rather than serializing them with null values. The same holds true in cases where you wish to filter fields as noted below.

• JSONP

  Clients that wish to access the API using JSONP will not be able to access the headers mentioned above. When supplying a JSONP callback, these headers will be encoded with the body of the response in the following format.

  $ curl -H "Authorization: Bearer {access_token}" 'https://api.meetup.com/find/groups?callback=foo&zip=10021'
  
  foo({
    "meta": {
      "next_link":"https://api.meetup.com/find/groups/?callback=foo&page;=200&zip;=10021&offset;=1",
      "total_count": 10171,
      // other headers
    },
    "data": // contents of the normal response
  )

  Note that the links from the Link header will be render with JSON keys in the form "{rel}_link".

Result Fields and Filters ¶

The results entity contains a list of the items that match the query criteria. Result fields are named values in these items, including simple values like strings and numbers, as well as entities that have values nested inside.

Optional Fields

Many API methods support optional result fields, as indicated in their documentation. One or more optional fields may be requested with the fields parameter, with names separated by commas. Since optional fields generally increase the processing time for a request, they should be requested only when needed.

https://api.meetup.com/recommended/groups?zip=10021&fields=join_info

Filtering Result Fields ¶

Result filters reduce the size of API responses. You can suppress result fields by specifying only and/or omit parameters. With only you will retrieve only those fields specified, and with omit you will retrieve all default fields excluding those specified.

The values of the only and omit parameters must be a comma-delimited list of fully qualified fields. You can specify nested sub-fields using periods. Both filters may be provided in the same request. See the examples below.

Examples

Search topics for "tech", but only include each topic's id and name (try in API Console):

https://api.meetup.com/find/topics?query=tech&only=id,name

Query for a group's recent sample of events, returning only the photo albums, but don't return the photo_sample nested in each photo_album:

https://api.meetup.com/:urlname?fields=event_sample&only=event_sample.photo_album&omit=event_sample.photo_album.photo_sample

Note that this feature is only available for json and xml formats.

Self alias ¶

Many of the query methods in the API require a member_id field for filtering. Sometimes you may want that member_id to be the id of the member who authorized an oauth token. To remove the need for an extra query to access that member_id, you may instead use the self alias in place of the member_id you would have to otherwise query for.

The following is an example of querying the /members/:member_id method for a member profile.

curl -H 'Authorization: Bearer {access_token}' 'https://api.meetup.com/members/self'

Try it yourself.

Event identifiers ¶

You should take note that event identifiers have unique properties compared to other types of entity identifiers. In particular, recurring event identifiers. If you post an rsvp for a recurring event using its string identifier in earlier versions of the API, all future calls relating to that event, will return an the integer version of its identifier. In the version all newer API methods, any reference to a recurring event should retain the string version of its identifier. If you post an rsvp for a recurring event in newer versions, you should expect the string identifier to remain intact.

Meta Headers ¶

You can optionally supply request headers which give the API more context for the request.

You can supply the HTTP header X-Meta-Visit with a value of a valid Meetup urlencoded group urlname or X-Meta-Visit-Event with a value of a valid Meetup event ID. This will inform the API that your application has a context for a user visiting a group. Some API methods that perform an action that creates data like RSVPing, and posting an event comment do this implicitly. You can provide this request header to provide the same context when querying for data. Organizers on the site often check their member lists sorted by the last time a member visited their group. Using this header will allow this list to be more accurate.

The X-Meta-Request-Headers header can specify a comma-delimited list of API-specific X-Meetup response header names to include in the response. The following header names are supported: unread-notifications, unread-messages, unread-updates, saved-events.

X-Meta-Request-Headers: unread-notifications

You should receive a response header named X-Meetup-Unread-Notifications whose value is the authenticated member's unread inbox item count.

X-Meta-Request-Headers: unread-messages

You should receive a response header named X-Meetup-Unread-Messages whose value is the authenticated member's unread message count.

X-Meta-Request-Headers: unread-updates

You should receive a response header named X-Meetup-Unread-Updates whose value is a total count of the authenticated member's unread inbox items and messages.

X-Meta-Request-Headers: saved-events

You should receive a response header named X-Meetup-Saved-Events whose value is the authenticated member's saved event count.

The X-Meta-Photo-Host header can specify a value of secure to have all photo links returned be hosted on a secure domain.

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. Except for JSON callbacks as noted below, error responses will have one of the following HTTP status codes:

• 400 Bad request when there was a problem with the request
• 401 Unauthorized when you don't provide a valid token
• 429 Too Many Requests when you've gone over your request rate limit
• 500 Internal Server Error an unexpected error occured on our servers

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 response body will have more detail.

A typical version 3 error response body will be serialized as JSON list of error objects, each with a code, message, and optionally a field property.

{
  "errors": [{
    "code": "field_error",
    "message": "field value was invalid",
    "field": "field_name"
  }, {
    "code": "non_field_error",
    "message": "other condition not met"
  }]
}

JSON requests that specify a callback parameter are treated differently: the API always responds with an HTTP status of 200, so that a client browser will load the response and handle the callback. When an error occurs its corresponding status line is served in a "status" field of the error response object rather than in the response header.

Limits and Throttling ¶

The Meetup API aims to provide consistent responsiveness and equal quality of service for all its consumers. In order to do so, we limit the frequency at which the API will produce successful responses to a single client.

You can know your current rate limit status by reading X-RateLimit HTTP headers included in responses. The following table indicates their name and meaning.

Header name	Meaning
X-RateLimit-Limit	The maximum number of requests that can be made in a window of time
X-RateLimit-Remaining	The remaining number of requests allowed in the current rate limit window
X-RateLimit-Reset	The number of seconds until the current rate limit window resets

Clients that issue too many requests in a short period of time will receive a HTTP 429 error and an error message.

In the version 1 and 2 API methods you will receive a message in this form:

{
  "details": "Credentials have been throttled",
  "problem": "Client throttled",
  "code": "throttled"
}

In the version 3 API methods you will receive a message in this form:

{
  "errors":[{
    "code": "throttled",
    "message": "Credentials have been throttled"
  }]
}

These responses indicate that you are making requests too quickly. If you receive one of these errors, you should adjust the frequency of your requests by adding a pause between them.

If you continue to issue requests at a frequency that triggers throttling responses, your credentials will be blocked for the remainder of the hour. You will know that your client is blocked when you receive a response with the error code "blocked".

In version 3 API methods you will receive a message in this form:

{
  "errors":[{
    "code": "blocked",
    "message": "Credentials have been throttled more than the allowed times in one hour"
  }]
}

Rather than issuing API requests until you are throttled and blocked, you will receive many more successful responses over time by tuning your client's request frequency such that it is not throttled at all.

Community ¶

Need more help? See our additional help documentation here.