Guide to Facebook events data

You can perform Facebook event searches by calling the Meta Content Library API client's search_events() method. This document describes the search_events() method and its syntax and parameters, and shows how to perform basic queries using the method.

All of the examples in this document 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:

search_events() method

This is the syntax of the search_events() method:

search_events(
    q=Q,
    fields=FIELDS,
    event_ids=EVENT_IDS,
    since=SINCE,
    until=UNTIL,
    event_since=EVENT_SINCE,
    event_until=EVENT_UNTIL  
)

The following table describes the parameters:

Sample queries

Search for events by keyword

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

library(contentlibraryapi)
        
# Create a client object if you have not already done so:
client <- ContentLibraryAPIClient$new(version='3')
        
# Create a search object:        
event_search <- client$search_events(q='cybercrime')
        
# No results are displayed until you provide display instructions:        
print(event_search$query_next_page())

from contentlibraryapi import ContentLibraryAPIClient

# Create a client object if you have not already done so:
client = ContentLibraryAPIClient.get_instance(version='3')

# Create a search object:
event_search = client.search_events(q="cybercrime")
        
# No results are displayed until you provide display instructions:
display(event_search.query_next_page())

This example would return only 10 results per page. You can keep calling query_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, create a search object using the search_events() method with the fields parameter and a comma-separated list of fields you want included. If omitted, default fields will be returned. To more easily see columns of data, this example specifies a DataFrame response format (the default response format is JSON).

# Create a search object including a list of fields:
event_search <- client$search_events(q='cybercrime', fields='id,name,description')        

# Specify DataFrame response format:       
print(event_search$query_next_page('dataframe'))

# Create a search object including a list of fields:
event_search = client.search_events(q='cybercrime', fields='id,name,description')

# Specify DataFrame response format:        
display(event_search.query_next_page('dataframe'))

DataFrame response format has clear columns:

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, create a search object using the search_events() method with the 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.

# Create a search object limiting the response to specific event IDs
event_search <- client$search_events(event_ids=['284083459792042'], fields='id,name,description,picture{url}')

# Create a search object limiting the response to specific event IDs
event_search = client.search_events(event_ids=['284083459792042'],  fields='id,name,creation_time')

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

Learn more

• Getting started
• Data dictionary
• Search guide
• Advanced search guidelines
• Guide to Facebook posts data