Guide to Facebook events data

You can perform Facebook event searches by calling the Meta Content Library API client get() method with the search/facebook_events path. This document describes the parameters, and shows how to perform basic queries by using the method.

All of the examples in this document are taken from a Researcher Platform use case and assume you have already created a Python or R Jupyter notebook and have created a client object. See Getting started to learn more.

See Data dictionary for detailed information about the fields that are available on a Facebook event node.

Recurring events

Recurring events have a parent event to which all instances of the recurring event are associated by way of the parent_event_id. The set of fields returned for an event search differs depending on whether the event returned is a parent or an instance (child) of the recurring event. Start and end times, for example, are specific to instances of the recurring event. The following table summarizes the differences:

Event type	Fields returned	Fields not returned
Recurring event (the "parent" event) (event_type=`recurring`)	`recurring_event_ids`	`attending_count` `interested_count` `event_start_time` `event_end_time` `parent_event_id`
Instance of recurring (the "child" event) (event_type=`instance_of_recurring`)	`attending_count` `interested_count` `event_start_time` `event_end_time` `parent_event_id`	`recurring_event_ids`

Parameters

Parameter	Type	Description
`Q` Optional	String	Keyword(s) to search for. See Advanced search guidelines for information about how multiple keyword searches with Boolean operators are handled.
`FIELDS` Optional	List	A comma-separated list of event fields you want included in search results. See Data dictionary for descriptions of all available fields.
`EVENT_IDS` Optional	List	A comma-separated list of Meta Content Library event IDs as strings. Limits the query to events in the list. Maximum of 250 IDs.
`SORT` Optional	Enum	Sort mode specifying the order in which the events are returned (only available for synchronous searches). Available options: `newest_to_oldest`: Events are returned in reverse chronological order (newest first). `most_to_least_people_going_count`: Events are returned based on the number of people going (most people going first). Default: `most_to_least_people_going_count` Note: Searches conducted in versions earlier than 5.0 had responses sorted in newest-to-oldest order by default. To achieve that same order, you must now specify `newest_to_oldest` with the `sort` parameter in your query.
`SINCE` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook events scheduled on or after this date or timestamp are returned (used with UNTIL to define a time range). SINCE and UNTIL are based on UTC time zone, regardless of the local time zone of the user who scheduled the event. If both SINCE and UNTIL are included, the search includes the time range defined by those values. If SINCE is included and UNTIL is omitted, the search includes the SINCE time through the present time. If SINCE is omitted and UNTIL is included, the search goes from the beginning of Facebook time through the UNTIL time. If SINCE and UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time. If SINCE and UNTIL are the same UNIX timestamp, the search includes the SINCE time through the SINCE time plus one hour. If SINCE and UNTIL are the same Date (YYYY-MM-DD), the search includes the SINCE date through the SINCE date plus one day.
`UNTIL` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook events scheduled on or before this date or timestamp are returned (used with SINCE to define a time range). SINCE and UNTIL are based on UTC time zone, regardless of the local time zone of the user who scheduled the event. If both SINCE and UNTIL are included, the search includes the time range defined by those values. If SINCE is included and UNTIL is omitted, the search includes the SINCE time through the present time. If SINCE is omitted and UNTIL is included, the search goes from the beginning of Facebook time through the UNTIL time. If SINCE and UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time. If SINCE and UNTIL are the same UNIX timestamp, the search includes the SINCE time through the SINCE time plus one hour. If SINCE and UNTIL are the same Date (YYYY-MM-DD), the search includes the SINCE date through the SINCE date plus one day.
`EVENT_SINCE` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook events started on or after this date or timestamp are returned (used with EVENT_UNTIL to define a time range). EVENT_SINCE and EVENT_UNTIL are based on UTC time zone, regardless of the local time zone of the user who started the event. If both EVENT_SINCE and EVENT_UNTIL are included, the search includes the time range defined by those values. If EVENT_SINCE is included and EVENT_UNTIL is omitted, the search includes the EVENT_SINCE time through the present time. If EVENT_SINCE is omitted and EVENT_UNTIL is included, the search goes from the beginning of Facebook time through the EVENT_UNTIL time. If EVENT_SINCE and EVENT_UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time. If EVENT_SINCE and EVENT_UNTIL are the same UNIX timestamp, the search includes the EVENT_SINCE time through the EVENT_SINCE time plus one hour. If EVENT_SINCE and EVENT_UNTIL are the same Date (YYYY-MM-DD), the search includes the EVENT_SINCE date through the EVENT_SINCE date plus one day.
`EVENT_UNTIL` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook events started on or before this date or timestamp are returned (used with EVENT_SINCE to define a time range). EVENT_SINCE and EVENT_UNTIL are based on UTC time zone, regardless of the local time zone of the user who started the event. If both EVENT_SINCE and EVENT_UNTIL are included, the search includes the time range defined by those values. If EVENT_SINCE is included and EVENT_UNTIL is omitted, the search includes the EVENT_SINCE time through the present time. If EVENT_SINCE is omitted and EVENT_UNTIL is included, the search goes from the beginning of Facebook time through the EVENT_UNTIL time. If EVENT_SINCE and EVENT_UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time. If EVENT_SINCE and EVENT_UNTIL are the same EVENT_UNIX timestamp, the search includes the EVENT_SINCE time through the EVENT_SINCE time plus one hour. If EVENT_SINCE and EVENT_UNTIL are the same Date (YYYY-MM-DD), the search includes the EVENT_SINCE date through the EVENT_SINCE date plus one day.

Sample queries

Search for events by keyword

To search for public events that contain specific keywords, use the get() method with the q parameter. See Advanced search guidelines for information about how multiple keyword searches are handled.

library(reticulate)
client <- import("metacontentlibraryapi")$MetaContentLibraryAPIClient

client$set_default_version(client$LATEST_VERSION)

response <- client$get(
        path = "search/facebook_events",
        params = list('q' = "cybercrime")
)
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Fetch next page
if (client$has_next_page(response)) {
    response <- client$query_next_page(response)
    jsonlite::fromJSON(response$text, flatten=TRUE) # Display second page
}

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

response = client.get(
    path="search/facebook_events",
    params={"q": "cybercrime"}
)
display(response.json()) # Display first page

# Fetch next page
if client.has_next_page(response):
    response = client.query_next_page(response)
    display(response.json()) # Display second page

You can keep calling query_next_page() and has_next_page() to get the next page of 10 results, until all the search results have been returned. See Search guide for other display and storage options.

Request specific fields

To have the API return only specific fields on any events in the response, use the fields parameter and a comma-separated list of fields you want included. If omitted, default fields will be returned.

library(reticulate)
client <- import("metacontentlibraryapi")$MetaContentLibraryAPIClient

client$set_default_version(client$LATEST_VERSION)

response <- client$get(
        path = "search/facebook_events",
        params = list("q" = "cybercrime", 'fields' = "id,name")
)
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

response = client.get(
        path="search/facebook_events", 
        params={q="cybercrime", 'fields':"id,name"}
)
display(response.json()) # Display first page

Search for events by event ID

You can search for Facebook events using specific event IDs obtained from previous event searches.

To get data on specific Facebook events that contain specific keywords or phrases, use the get()method with q parameter (specifying the keywords or phrases) and the event_ids parameter (specifying the list of event IDs you want included). If you omit the q argument, all events in the list of IDs are included, not just those with a specific keyword or phrase.

response <- client$get(
        path = "search/facebook_events", 
        params = list("event_ids" = list('284083459792042'), 'fields' = "id,name")
)

jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
       path="search/facebook_events", 
       params={"event_ids": ['284083459792042', 'fields':"id,name"}
)

display(response.json()) # Display first page

For using event IDs to search for posts from specific Facebook events, see Guide to Facebook posts data.