ID-based retrieval

This feature allows you to fetch a Meta Content Library node using its Meta Content Library ID. We support the following nodes for ID-based retrieval:

Facebook posts
Facebook groups
Facebook events
Facebook Pages
Facebook comments
Facebook profiles
Instagram posts
Instagram accounts
Instagram comments

We also support retrieval of edges to a node. An edge is a connection between two nodes. For example, the Facebook post node can have comments connected to it.

See Data dictionary for detailed information about the fields on each node.

Getting started with ID-based retrieval

Meta Content Library IDs can be used in queries and displayed in the search results. Meta Content Library IDs are unique IDs linked to an entity in MCL. These IDs cannot be used to search on Meta’s technologies.

To get sample Meta Content Library IDs users can do a search query defined here. The response of these queries will give a list of Meta Content Library entities with a field ID. This ID field can be used for ID-based retrieval by following the steps below.

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

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

# Get the response of MCL ID
response <- client$get(path="MCL_ID")

# Display the response
jsonlite::fromJSON(response$text)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

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

# Get the response of MCL ID
response = client.get(path="MCL_ID")

# Display the response 
display(response.json())

The following table describes the parameters:

Parameter	Type	Description
`path`	String	Meta Content Library ID.
`version`	Optional [String]	Optional version of Meta Content Library API.

Get edge

Below is the syntax for fetching content library ID-based retrieval edge:

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)

# Get the response of the edge of MCL ID with optional params fields
response <- client$get(
        path="<MCL_ID>/<EDGE>",
        params=list("fields" = FIELDS)
)

# Display the response
jsonlite::fromJSON(response$text)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

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

# Get the response of the edge of MCL ID with optional params fields
response = client.get(
        path="<MCL_ID>/<EDGE>",
        params={"fields" : FIELDS}
)

# Display the response
display(response.json())

The following table describes the parameters:

Parameter	Type	Description
`PATH`	String	Meta Content Library ID, followed by edge.
`PARAMS` Optional	List	Comma-separated list of fields you want included in the result. See Data dictionary for descriptions of all available fields.

Get asynchronous edge

Similarly to how asynchronous search works, you can fetch an edge that returns multiple entries, with an asynchronous request.

When you submit an asynchronous query, the API returns a handle ID indicating the successful submission of the asynchronous query if the expected results are below the 100,000 query results limit, and an error message if the expected results are over the limit.

If the query is successfully submitted, you can check on the status and receive either IN_PROGRESS or COMPLETE.

Submit an Asynchronous query using get

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

client$set_default_version(client$LATEST_VERSION)

# Submit query as an async  
response <- client$get(
        path="<MCL_ID>/async_<EDGE_NAME>" , 
        params=list("fields" = FIELDS)
)

# Returns IN_PROGRESS or COMPLETE
status_response <- async_utils$get_status(response=response)
jsonlite::fromJSON(status_response$text)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client
from metacontentlibraryapi import MetaContentLibraryAPIAsyncUtils as async_utils

client.set_default_version(client.LATEST_VERSION)

# Submit query as an async  
response = client.get(
         path="<MCL_ID>/async_<EDGE_NAME>",
         params={"fields" : FIELDS}
)

# Returns IN_PROGRESS or COMPLETE
status_response = async_utils.get_status(response=response)
display(status_response.json())

Get data

When the check for status shows COMPLETE, you can fetch the data. You can also write the data to a file, which will be stored in the /previous_queries/ folder in your Jupyter environment in JSON format.

data_response <- async_utils$get_data(response=response)
jsonlite::fromJSON(data_response$text, flatten=TRUE)

# Write data to file using below command
async_utils$write_data_to_file(response=response, file_name=FILENAME)

get_data_response = async_utils.get_data(response=response)
display(get_data_response.json())

# Write data to file
async_utils.write_data_to_file(response=response, file_name=FILENAME)

The following table describes the parameters for write_to_file method:

Parameter	Type	Description
`FILE_NAME`	String	Custom filename to write generated data.

Estimate response size for asynchronous queries

Use the estimate param to get a rough idea of how much data would be returned from an edge query you have defined. Since the API can only return up to 100,000 results from a single asynchronous query, it can be helpful to know in advance if your query is likely to fail because the response size is too large. If the estimate comes out higher than 100,000, consider modifying the parameters to reduce the response size. You can continue to modify the query parameters and get new estimates until the results are predicted to fall below the maximum allowed.

This example is typically most useful for posts with many comments because the number of results tend to be higher, but it can be used to estimate the size of data that would be returned by any query.

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

client$set_default_version(client$LATEST_VERSION)

# Get summary of results by making sure to pass field summary and set it to True
response <- client$get(
       path="MCL_ID/EDGE_NAME",    
       params=list( fields="FIELDS"), 
       estimate=TRUE
)

jsonlite::fromJSON(response$text, flatten=TRUE)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Get summary of results by making sure to pass field summary and set it to True
response = client.get(
           path="MCL_ID/EDGE_NAME",     
           params={"fields": "FIELDS"},
           estimate=True
)

# Display the json response
display(response.json())

Sample queries

Fetch Facebook Page by Page ID

# Sample query for Python library for ID-based retrieval of a Facebook page with optional param fields
library(reticulate)
client <- import("metacontentlibraryapi")$MetaContentLibraryAPIClient

client$set_default_version(client$LATEST_VERSION)

# Fetch the entity by calling the get method with optional fields parameter
response <- client$get(
       path="990512972055041",
       params=list("fields"="about,description")
)

# Print the Meta Content Library entity
jsonlite::fromJSON(response$text, flatten=TRUE)

# Sample query for Python library for ID-based retrieval of a Facebook page with optional param fields
from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Fetch the entity by calling the get method with optional fields parameter
response = client.get(
        path="990512972055041",
        params={"fields": "about,description"}
)

# Print the Meta Content Library entity
display(response.json())

Fetch comments on a post

Comments can be fetched both for Facebook and Instagram posts. The following examples use a Facebook post, but the same structure applies to Instagram posts.

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

client$set_default_version(client$LATEST_VERSION)

# Fetch comments by calling /comments edge, with a POST Meta Content Library ID
response <- client$get(
        path = "1927859627616307/comments", 
        params=list("fields"="owner,creation_time")
)

# Fetch results
jsonlite::fromJSON(response$text, flatten=TRUE)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Fetch comments by calling /comments edge, with a Post Meta Content Library ID
response = client.get(
       path="1927859627616307/comments",
       params={"fields" : "owner,creation_time"}
)
# Fetch results
display(response.json())

The example above returns 10 results per page. You can use the query_next_page() and has_next_page() to get the next page of 10 results until all the results have been returned. As described above, the synchronous query can return up to 1,000 results. Asynchronous query should be used instead if there are more than 1.000 comments available.

all_comments <- list()

# Check if a post has next page and if it exists fetch the next page
while  (client$has_next_page(response)) {
     comments <- jsonlite::fromJSON(response$text, flatten = TRUE)$data

     all_comments <- dplyr::bind_rows(all_comments, comments)

     # Get next page
    response <- client$query_next_page(response)
}

# Display the response
all_comments

all_comments = []

# Check if a post has next page
while (client.has_next_page(response)):
    comments = response.json()['data']

    all_comments = all_comments + comments

    # Get next page
    response = client.query_next_page(response)

# Display the response
display(all_comments)

Asynchronously fetch comments on a post

Submit asynchronous query

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

client$set_default_version(client$LATEST_VERSION)

# Submit query as an async  
response <- client$get(path="1927859627616307/async_comments")

jsonlite::fromJSON(response$text, flatten=TRUE)

from metacontentlibraryapi import (
    MetaContentLibraryAPIClient as client, 
    MetaContentLibraryAPIAsyncUtils as async_utils)

client.set_default_version(client.LATEST_VERSION)

        
        # Submit query as an async
response = client.get(path="1927859627616307/async_comments")

display(response.json())

Check status

# Returns IN_PROGRESS or COMPLETE
status_response <- async_utils$get_status(response=response)
jsonlite::fromJSON(status_response$text, flatten=TRUE)

# Returns IN_PROGRESS or COMPLETE
status_response = async_utils.get_status(response=response)
display(status_response.json())

Once STATUS is COMPLETE, fetch data

# Fetch data  
data_response <- async_utils$get_data(response=response)
jsonlite::fromJSON(data_response$text, flatten=TRUE)

# Fetch data  
data_response = async_utils.get_data(response=response)
display(data_response.json())

Estimating comments

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

client$set_default_version(client$LATEST_VERSION)

# Get summary of results by making sure to pass field summary and set it to True
response <- client$get(
        path = "1927859627616307/comments", 
        params=list("fields"="owner,creation_time", "summary"=TRUE)
)

# Fetch results
jsonlite::fromJSON(response$text, flatten=TRUE)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Get summary of results by making sure to pass field summary and set it to True
response = client.get(
        path="1927859627616307/comments",
        params={"fields": "owner,creation_time", "summary": True},
)

# Display the json response
display(response.json())