Getting started

You can work with Meta Content Library API within Meta Secure Research Environment or within an approved third-party cleanroom environment. The getting started procedure documented here is specific to Secure Research Environment which runs a modified version of Jupyter within an Amazon WorkSpaces Secure Browser instance 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 Secure Research Environment:

• Log in to the Secure Research Environment URL
• Create a Jupyter notebook
• Import the Content Library API client
• Test with a basic search

Log in to the Secure Research Environment URL

Use one of the two available Amazon WorkSpaces Secure Browser portals to access Content Library API in Secure Research Environment. For the best user experience and platform performance, select the portal closest to your location:

• United States portal
• Ireland portal

See WorkSpaces Secure Browser in the Secure Research Environment user documentation for more information about WorkSpaces Secure Browser.

Log into the site using your Facebook credentials. This will spin up an instance of JupyterHub server for your use in Secure Research Environment.

You will be offered the choice of CPU or GPU server. See GPU server to learn about the difference between the two. See Secure Research Environment for complete Secure Research Environment documentation.

Create a Jupyter notebook

In the Launcher window, click the icon for Python3 or R. This will create a new Jupyter Notebook in a new browser tab. To rename 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 run icon in the top toolbar.

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="facebook/pages/preview",
        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="facebook/pages/preview",
    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=paste0("facebook/pages/", 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="facebook/pages/" + page_mcl_id,
)

display(single_page_response.json())

Learn more

• Jupyter
• JupyterLab documentation
• Jupyter Notebook basics
• Secure Research Environment documentation