Guide to Facebook fundraisers data

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

All of the examples in this document are taken from a Secure Research Environment use case and assume you have created a Jupyter notebook and a client object. See Getting started to learn more.

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

Parameters

Parameter	Type	Description
`Q` Optional	String	Keyword(s) to search for. Searches fundraiser `title` and `description` fields. See Advanced search guidelines for information about how multiple keyword searches with Boolean operators are handled.
`SORT` Optional	Enum	Sort mode specifying the order in which fundraisers are returned (only available for synchronous searches). Available options: `most_to_least_donors`: Fundraisers are returned based on the number of donors that have contributed to the fundraiser (most donors first). `newest_to_oldest`: Fundraisers are returned in reverse chronological order (newest first). `oldest_to_newest`: Fundraisers are returned in chronological order (oldest first). Default: `most_to_least_donors`
`NONPROFIT_CATEGORIES` Optional	List	Comma-separated list of fundraiser category names to include in the search (only available for fundraisers where the beneficiary is a nonprofit). Keywords can be used to match categories. Categories are visible in the Meta Content Library UI.
`NONPROFIT_COUNTRIES` Optional	List	Comma-separated list of countries to include. This refers to countries of the nonprofit associated with the fundraiser. Only available for fundraisers where the beneficiary is a nonprofit. Takes ISO Alpha-2 Country Code in 2-letter uppercase format.
`NONPROFIT_IDS` Optional	List	Comma-separated list of nonprofit IDs to include (only available for fundraisers where the beneficiary is a nonprofit).
`OWNER_IDS` Optional	List	Comma-separated list of Meta Content Library Owner IDs as strings. Limits the query to fundraisers organized by owners in the list. Maximum of 250 IDs.
`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. Fundraisers created 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 producer who organized the fundraiser. 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. Fundraisers created 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 producer who organized the fundraiser. 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.

Sample queries

Search for fundraisers by keyword

To search for fundraisers whose title or description contain specific keywords, use the q parameter. See Advanced search guidelines for information about how multiple keyword searches are handled.

This example shows how to iterate through responses by using the query_next_page() method. You can keep calling query_next_page() to get the next page of 10 results, until all the search results have been returned. You can call has_next_page() to check if there is more data. See Search guide for other display and storage options.

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

client$set_default_version(client$LATEST_VERSION)

response <- client$get(path="facebook/fundraisers/preview", params=list("q"="animals"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Fetch next page
if (client$has_next_page(response)) {
    response <- client$query_next_page(response)

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

response = client.get(
    path="facebook/fundraisers/preview",
    params={"q":"animals"},
)
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

Search for fundraisers by nonprofit country

In addition to searching for fundraisers based on a keyword, this example limits the results to fundraisers in a specified country.

response <- client$get(path="facebook/fundraisers/preview", params=list("nonprofit_countries"="US", "q"="children"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
    path="facebook/fundraisers/preview",
    params={"nonprofit_countries":["US"], "q":"children"},
)
display(response.json()) # Display first page

Search for fundraisers by nonprofit category

This example retrieves fundraisers in the specified categories whose title or description match the specified keyword. You can consult the Meta Content Library UI for the current list of available categories.

response <- client$get(path="facebook/fundraisers/preview", params=list("nonprofit_categories"="education, health", "q"="children"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
    path="facebook/fundraisers/preview",
    params={"nonprofit_categories":["education", "health"], "q":"children"},
)
display(response.json()) # Display first page

Search for fundraisers by nonprofit IDs

To search for fundraisers benefitting specific nonprofits, use the NONPROFIT_IDS parameter, providing IDs you obtained from the results of previous queries. This type of search is only available for fundraisers where the beneficiary is a nonprofit.

response <- client$get(path="facebook/fundraisers/preview", params=list("nonprofit_ids"= list("1687800528495896","2258893424505921"), "q"="children"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
    path="facebook/fundraisers/preview",
    params={"nonprofit_ids":["1687800528495896", "2258893424505921"], "q":"children"},
)
display(response.json()) # Display first page

Search for fundraisers by owner IDs

Similar to searching based on specific nonprofit IDs, you can also search based on specific owner IDs, as shown in the following example. Again, you would have obtained the IDs from the results of a previous search.

response <- client$get(path="facebook/fundraisers/preview", params=list("owner_ids"="1278397396204099", "q"="animals"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
    path="facebook/fundraisers/preview",
    params={"owner_ids":["1278397396204099"], "q":"animals"},
)
display(response.json()) # Display first page