addressalign-toparrow-leftarrow-rightbackbellblockcalendarcameraccwcheckchevron-downchevron-leftchevron-rightchevron-small-downchevron-small-leftchevron-small-rightchevron-small-upchevron-upcircle-with-checkcircle-with-crosscircle-with-pluscontroller-playcredit-cardcrossdots-three-verticaleditemptyheartexporteye-with-lineeyefacebookfolderfullheartglobe--smallglobegmailgooglegroupshelp-with-circleimageimagesinstagramFill 1languagelaunch-new-window--smalllight-bulblinklocation-pinlockm-swarmSearchmailmediummessagesminusmobilemoremuplabelShape 3 + Rectangle 1ShapeoutlookpersonJoin Group on CardStartprice-ribbonprintShapeShapeShapeShapeImported LayersImported LayersImported Layersshieldstartickettrashtriangle-downtriangle-uptwitteruserwarningyahooyoutube

Extend your community

Find Upcoming Events

GET /find/upcoming_events
  • json
Host: api.meetup.com
  • basic
api version 3

Returns a list of upcoming events

Try it in the console

Request Parameters

By default, the events returned will be based on the hosting groups near the authenticated member's location. To customize this location, send a valid "lat" and "lon" parameter combination reflecting a desired location.

You may filter results using an topic category identifier from the Topic Categories API

You may specify 'fields' to expand response events with corresponded fields

end_date_range

Return events that start before this date. The date must follow this format: YYYY-MM-DDTHH:MM:SS.

end_time_range

Return events that start before this time. The time must follow this format: HH:MM:SS. The time is exlusive. A start_time_range must also be present

excluded_groups

IDs for groups to exclude from the returned events. excluded_groups overrides the include and only values for self_groups. In other words, if excluded_groups is nonempty, then groups specified in excluded_groups will be excluded even if they are in the set of groups the authenticated member belongs to.

fields

A comma-delimited list of optional fields to populate in the response

lat

Approximate target latitude

lon

Approximate target longitude

order

The sort order of returned events. Valid values include: 'best' and 'time'. 'best' orders events by recommendation score, while 'time' orders events by the by the event's start time in increasing order. Defaults to 'best'.

page

A target minimum number of events to return in a single page of results. The number returned is non-deterministic but a best-effort attempt will be made to return at least some. Defaults to 32

radius

Radius in miles. May be 0.0-100.0, 'global' or 'smart', a dynamic radius based on the number of active groups in the area. Defaults to member's preferred radius

self_groups

set to 'include' or 'exclude' or 'only' get groups that the member belongs to. Defaults to 'include.' When self_groups is set to only and the order is set to time, the following fields are disregarded: page, end_date_range, lat and lon.

start_date_range

Return events that start after this date. The date must follow this format: YYYY-MM-DDTHH:MM:SS. It defaults to the current date and time.

start_time_range

Return events that start after this time. The time must follow this format: HH:MM:SS. The time is inclusive. An end_time_range must also be present.

text

Full text search query

topic_category

Numeric topic category identifier for filtering recommendations by a topic category

Response

Returns a list of event objects and the resolved city

city

The current city in context

city

The name of the city

country

The ISO_3166-1 country code for the country which contains the city

id

Numeric identifier of the city

lat

The latitude of the city

lon

The longitude of the city

member_count

The number of Meetup members in the city

name_string

The full name of the city, as returned by query search, if applicable

state

The state which contains the city, if applicable

zip

The zip code of the city. For cities in countries without ZIP codes, a placeholder will be returned

events

List of events

attendance_count

Number of all members marked as attended, yes RSVPs that were not changed by attendance and their guests

attendance_sample

A small collection of members marked as attended and yes RSVPs that were not changed by attendance

attendee_sample

A small collection of attendance records of members marked as attended and yes RSVPs that were not changed by attendance. For upcoming events, this represents collection of yes RSVPs

comment_count

An aggregate count of all comments and replies for a given event, returned when fields request parameter value includes 'comment_count'

created

Creation time of the event, in milliseconds since the epoch

description

Description of the event in HTML. Email addresses and phone numbers will be masked for non-members

description_images

A list of image urls included in the event description. returned when "fields" request parameter value contains "description_images, only supported for GET /event/:id currently"

duration

Scheduled event duration in milliseconds, if an end time is specified by the organizer. When not present, a default of 3 hours may be assumed by applications

event_hosts

List of members hosting the event, returned when fields request parameter value includes 'event_hosts'

host_count

Number of times member hosted for group

id

Host member's id

intro

Host member's introduction

join_date

Group join date in milliseconds since epoch

name

Host member's name

photo

Member photo if one exists

featured

Boolean indicator of whether or not a given event is featured, returned when fields request parameter value includes 'featured'

featured_photo

A featured photo for this event, returned when the 'fields' request paramater includes 'featured_photo'

base_url

A base url that can be use to construct a photo url from its components

highres_link

Link for full sized photo

id

Numeric photo ID

photo_link

Link for standard sized photo

thumb_link

Link for thumbnail sized photo

type

Type of photo. One of "event" or "member"

fee

Ticketing fee information for events that support payments

accepts

Acceptable methods of payments may be one of "paypal", "wepay", or "cash"

amount

Amount of the fee

currency

Currency accepted for fee

description

Fee description, typically "per-person"

label

Label for fee, typically "Price"

required

Boolean flag indicating if this fee is required to RSVP

fee_options

Payment options for event ticketing, returned when the 'fields' request parameter value includes 'fee_options'

currencies

Acceptable currencies for the payment method specified by type

is_setup

A boolean set to true if the payment method specified by 'type' is set up for the group

setup_link

The URL for setting up the payment method specified by 'type'. This is returned if the payment method specified by 'type' is not set up for the group and the member has the permission to set it up

type

Acceptable methods of payments may be one of Set(none, cash, paypal, wepay)

group

Information about group hosting the event

category

Category group belongs to, returned when fields request parameter value includes 'group_category'

country

Country of the group

id

Numeric identifier for the group

join_info

Lists any questions requested when joining and required fields. Returned with "fields" request parameter value includes "group_join_info"

join_mode

Indicator of how new members may be able to join. be one of "open", "approval" or "closed"

key_photo

Group primary photo, returned when fields request parameter value includes 'group_key_photo'

lat

Approximate group latitude

localized_location

City/State or City/Country of the group

lon

Approximate group longitude

membership_dues

Membership dues information associated with hosting group, returned when fields request parameter value includes 'group_membership_dues'

meta_category

The meta category of the group, if the group has one, returned when fields request parameter value inclues 'meta_category'

name

Name of the group

past_event_count

The number of past events belonging to the group, returned when "fields" includes "group_past_event_count"

photo

Photo associated with group, returned when fields request parameter value includes 'group_photo'

photo_gradient

Color combination used to generate group duotone, returned when fields request parameter value includes 'group_photo_gradient'

pro_network

Information on group's Pro organization, returned when "fields" request parameter value includes "group_pro_network"

region

Language and region of the group

self

Information pertaining to the authenticated member with respect to the group, returned when fields request parameter value includes 'group_self_profile', 'group_self_actions', 'group_self_membership_dues', or 'group_self_status'

state

State of the group

timezone

Timezone of group

topics

Topics related to the group, returned when fields request parameter value includes 'group_topics'

urlname

Alphanumeric urlname identifier for the group

visibility

Group visibility, returned when fields request parameter value includes 'group_visibility'. Value may be "public", "public_limited", or "members".

who

What the group calls its members

how_to_find_us

Additional information on how to find members at a venue when provided by an organizer, returned when fields request parameter value includes 'how_to_find_us'

id

A unique alphanumeric identifier for event

link

Link to event on meetup.com

local_date

The local date of the Meetup in ISO 8601 format

local_time

The local time of the Meetup in ISO 8601 format

manual_attendance_count

Manually entered total attendee headcount, if any exists

name

Name of the event

past_event_count_inclusive

Number of past events that happened before and including this event. Returned when "fields" request parameter value contains "past_event_count_inclusive"

photo_album

Information about photo uploads for this event, returned when fields request parameter value includes 'photo_album'

event

Event photo album belongs to. This will be absent if the album is not associated with an event

id

Unique numeric identifier for photo album

photo_count

Number of photos uploaded

photo_sample

A small collection of photos uploaded for this event

title

Album title

plain_text_description

Plain text version of the event description. Email addresses and photo numbers will be masked for non-members. Returned when "fields" request parameter value contains "plain_text_description"

plain_text_no_images_description

Plain text version of the event description without images. Email addresses and photo numbers will be masked for non-members. Returned when "fields" request parameter value contains "plain_text_no_images_description"

rsvp_close_offset

The amount of time between when RSVPs close and the start time of the Meetup in ISO 8601 format

rsvp_limit

The number of "yes" RSVPS an event has capacity for

rsvp_open_offset

The amount of time between when RSVPs open and the start time of the Meetup in ISO 8601 format

rsvp_rules

Information about conditions that allow for member RSVPs, returned when fields request parameter value include 'rsvp_rules'

close_time

UTC time that RSVPs will no longer be accepted, though organizers may close RSVPs earlier

closed

Boolean value indicating whether or not RSVPing was explicitly closed for the event.

guest_limit

Number of guests members may include in their RSVP, 0 or more

open_time

UTC time that members may begin to RSVP

refund_policy

The organizer-defined terms for refunds. If this is defined, you must provide the authenticated member a way to access this information before they can RSVP. They will need to agree to these terms before they RSVP

waitlisting

Wait list handling when RSVP limit is reached. Value may be one of 'auto', 'manual' or 'off'

rsvp_sample

A small collection RSVPs for members attending this event, returned when fields request parameter value includes 'rsvp_sample'

created

Creation time of the RSVP, in milliseconds since the epoch

id

Unique numeric identifier for the RSVP. May be -1 for events scheduled in the future

member

Member who RSVP'd

updated

Last modified time of the RSVP, in milliseconds since the epoch

rsvpable

Boolean value indicating whether or not the authenticated member can RSVP or join the waitlist when the event is full. Returned when the "fields" request parameter value includes "rsvpable"

rsvpable_after_join

Boolean value indicating whether or not the authenticated member can RSVP after joining the hosting group. Returned when the "fields" request parameter includes "rsvpable_after_join" and the authenticated member is not a member of the group hosting this event

saved

Whether the authorized member has saved the event, returned when fields request parameter value includes 'saved'

self

represents details particular to the authorized user, only present if requested and authenticated member is a member of the hosting group, returned when fields request parameter value includes 'self'

actions

List of actions the authenticated member may perform, potentially one or more of the following

"announce" to announce the event to the group's members

"attendance" to view or take attendance for the event

"copy" the ability to copy an event

"comment" the ability to post a comment or reply

"payments" the ability to mark members as paid if the event is ticketed

"publish" to publish a draft event

"edit" to edit the event information

"edit_hosts" to edit the hosts for the event

"email_attendees" the ability to email event attendees

"delete" to delete the event

"rsvp" to RSVP yes or no to the event

"wait" to get on the waiting list (using the same RSVP methods).

"dues" if an organizer requires membership dues to RSVP and the authorized member has not paid theirs

"upload_photo" the ability to upload a photo for the event

"cancel" the ability to cancel the event

"close" the ability to close the RSVPs for the event

"open" the ability to open the RSVPs for the event

"invite" the ability to invite someone for the event

"download_attendees" the ability to download the attendees list for the event

"take_attendance" the ability to take attendance for the event

"delete_cancelled" the ability to delete the event if it is cancelled

pay_status

The authenticated member's payment status. This may be one of 'none', 'paid', 'partially_paid', 'payment_pending', 'echeck_pending', 'refund_pending', 'partially_refunded', 'refunded'

role

The authenticated member's role in within the group, if any. This may be one of: Organizer, Assistant Organizer, Event Organizer, etc.

rsvp

Member's RSVP, if any

series

Returned when the "fields" request parameter value includes "series" for events that are part of a series of events

description

Human displayable description of how often events in this series occur

end_date

Date when this series ends/ended, in milliseconds since the epoch

id

Unique numeric identifier for the series

monthly

Returned for events that are part of a monthly recurring series of events

start_date

Date when this series begins/began, in milliseconds since the epoch

template_event_id

Unique numeric identifier for the template event of the series

weekly

Returned for events that are part of a weekly recurring series of events

short_link

A shortened link for the event on meetup.com, returned when fields request parameter value includes "short_link"

simple_html_description

Description of the event, in simple HTML source format. If this event's description was saved in simple HTML format, the description field will be an HTML translation of this source. Returned when the "fields"' request parameter contains "simple_html_description"

status

"cancelled", "upcoming", "past", "proposed", "suggested", or "draft"

survey_questions

List of organizer-defined survey questions intended to be asked of RSVPing members. Returned when the "fields"' request parameter contains "answers"

id

Numeric question identifier

question

Question text

time

UTC start time of the event, in milliseconds since the epoch

updated

Last modified time for the event in milliseconds since the epoch

utc_offset

The local offset from UTC time, in milliseconds

venue

The event venue, present only if selected and not hidden by an organizer

address_1

Line 1 of venue address

address_2

Line 2 of venue address

address_3

Line 3 of venue address

city

City of venue

country

Country code of venue

id

Unique numeric venue id

lat

Approximate latitude

localized_country_name

The localized name of the venue's country

lon

Approximate longitude

name

Venue name

phone

Phone number of venue

repinned

true if the editor of the event altered the original venues pin location, false otherwise

state

State of venue where available

zip

ZIP code if, venue is in US or Canada

venue_visibility

Represents who can see the venue with a potential value of "members" or "public", returned when fields request parameter value includes "venue_visibility" and the authenticated member is a member of the group hosting the event

visibility

Event visibility: "public", "public_limited", or "members". Events in private groups that do not expose limited information are visible only to that group's members and should not be made public.

waitlist_count

Number of members on the waitlist, if one exists

web_actions

Set of "Invite" and google/yahoo/ical/outlook "Add to calendar" web actions

why

We should do this because...

yes_rsvp_count

Number of yes RSVPs including guests

API methods

v3 batch

v2 categories

v2 cities

v2 dashboard

v1 groups

v1 oembed

v1 topics

v2 deprecated