Getting started

You can work with Meta Content Library API within Meta Researcher Platform or within an approved third-party cleanroom environment. The getting started procedure documented here is specific to Researcher Platform which runs a modified version of Jupyter and provides you with a virtual data cleanroom where you can securely search for and analyze data. If you are accessing the Content Library API through a third-party cleanroom environment, you will be provided with getting started instructions from the cleanroom's system administrator.

To get up and running with Content Library API in Researcher Platform:

• Set up OpenVPN
• Log in to the Researcher Platform URL
• Create a Jupyter notebook
• Import the Content Library API client
• Test with a basic search

Set up OpenVPN

Until January 7, 2025, you can access Content Library API through a Virtual Private Network (VPN). This section shows you how to install and configure the OpenVPN client and connect to our VPN server. Once connected, you will be able to use Content Library API.

Step 1: Download and install OpenVPN

When the setup wizard completes, OpenVPN Connect launches and you will be required to accept the OpenVPN Inc. Data Collection, Use and Retention policy to continue.

Step 2: Set up your profile

In the Import Profile window, select the UPLOAD FILE tab.

Step 3: Download the OpenVPN configuration file

Clicking this link downloads the OpenVPN configuration file (fortVpnCredentials.ovpn) to your computer (check your downloads folder). Once downloaded, drag and drop the file into the Import Profile window.

Step 4: Connect to the VPN

In the Imported Profile window, click CONNECT.

Once successfully connected, you will see this window:

Log in to the Researcher Platform URL

While connected to the VPN, go to the Researcher Platform URL.

If you'd like to use the latest Amazon WorkSpaces Secure Browser version of Researcher Platform, you can follow this URL without being connected to the VPN.

Log in to the site using your Facebook credentials. This will spin up an instance of JupyterHub server for your use in the Researcher Platform.

You will be offered the choice of CPU or GPU server. You can learn more about the difference between the two here and there is complete documentation on Researcher Platform here.

Create a Jupyter notebook

To create a new notebook:

1. In your Jupyter hub environment, click the blue "+" symbol in the upper left corner of the window.

2. Under Notebook in the Launcher tab, select Python 3 or R according to your preferred language. This creates and opens a new Jupyter notebook.

To name the notebook, right-click the notebook in the left navigation bar and select Rename.

You enter queries in the blank cells of the notebook. To run a query, click the play icon.

Import the Content Library API client

All calls are made using the Content Library API Client. You only need to import the Content Library API client once per Jupyter notebook server session.

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

# Set specific MCL_API_VERSION, or use client$LATEST_VERSION to get the latest 
client$set_default_version(client$LATEST_VERSION)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

# Set specific MCL_API_VERSION, or use client.LATEST_VERSION to get the latest 
client.set_default_version(client.LATEST_VERSION)

Test with a basic search

Test your setup by running a basic search query. Here is an example to try for Facebook Pages:

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

client$set_default_version(client$LATEST_VERSION)

# Search for Facebook Pages
pages_response <- client$get(
        path="search/facebook_pages",
        params = list("q"="mountains")
)
 
jsonlite::fromJSON(pages_response$text, flatten=TRUE) # Display first page

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Search for Facebook Pages
pages_response = client.get(
    path="search/facebook_pages",
    params={"q": "mountains"}
)

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

Test fetching by Meta Content Library ID

Test fetching an entity by its ID (obtained from the results of a previous search) such as one of the Pages from the previous query:

pages_data <- jsonlite::fromJSON(pages_response$text, flatten=TRUE)$data
page_mcl_id <- pages_data[c('id')][1,]

# Fetch by Meta Content Library ID
response <- client$get(path=page_mcl_id)
 
jsonlite::fromJSON(response$text, flatten=TRUE)

page_mcl_id = pages_response.json()['data'][0]['id']

# Fetch by Meta Content Library ID
single_page_response = client.get(
    path=page_mcl_id,
)

display(single_page_response.json())

Learn more

• Jupyter
• JupyterLab documentation
• Jupyter Notebook basics
• Researcher Platform documentation