Graph API Version

Topic Search API

The Topic Search API returns the Topic ID and other related information for a topic that that can be inputted in plain text. The Topic ID is used in the Topic Feed API and Topic Insights API to query for additional data around the topic.

Reading

Fields

NameDescriptionType

q

The topic that you want to get the ID for. All UTF-8 encoded strings are supported (e.g. über).

This field is required.

string

fields

The fields that you can ask to return. You can ask for the following fields using a comma-separated string:

  • id - The topic ID
  • name - The topic name
  • page- The page associated with the topic ID, including its name, category, and page ID

This field is optional. If you omit it, only the id will be returned by default.

string

Results

NameDescription

id

The topic ID.

name

The topic name.

page

The page associated with the topic ID, including its name, category, and page ID.

Samples

For example, suppose you want to query for the topic ID, name, and associated page for the string lebron james:

Graph API Explorer
/* make the API call */
FB.api(
    "/search",
    {
        "type": "topic",
        "q": "lebron james",
        "fields": "id,name,page"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
GET /v2.8/search?type=topic&q=lebron+james&fields=id%2Cname%2Cpage HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/search',
  array (
    'type' => 'topic',
    'q' => 'lebron james',
    'fields' => 'id,name,page',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
Bundle params = new Bundle();
params.putString("type", "topic");
params.putString("q", "lebron james");
params.putString("fields", "id,name,page");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/search",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"type": @"topic",
  @"q": @"lebron james",
  @"fields": @"id,name,page",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/search"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

This could return:

{
  "data": [
    {
      "id": "dG9waWNfNjQ2Mzc2NTM5NDM=", 
      "name": "LeBron James", 
      "page": {
        "category": "Athlete", 
        "name": "LeBron James", 
        "id": "64637653943"
      }
    }
  ]
}

It's also possible for the API to return multiple topic IDs. For example, here's a query for clinton:

Graph API Explorer
/* make the API call */
FB.api(
    "/search",
    {
        "type": "topic",
        "q": "clinton",
        "fields": "id,name,page"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
GET /v2.8/search?type=topic&q=clinton&fields=id%2Cname%2Cpage HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/search',
  array (
    'type' => 'topic',
    'q' => 'clinton',
    'fields' => 'id,name,page',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
Bundle params = new Bundle();
params.putString("type", "topic");
params.putString("q", "clinton");
params.putString("fields", "id,name,page");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/search",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"type": @"topic",
  @"q": @"clinton",
  @"fields": @"id,name,page",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/search"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

This could return:

{
  "data": [
    {
      "id": "dG9waWNfMTI5MTE3MzQwNDYzNTU2", 
      "name": "Clinton County, New York", 
      "page": {
        "category": "State/province/region", 
        "category_list": [
          {
            "id": "209889829023118", 
            "name": "Landmark"
          }
        ], 
        "name": "Clinton County, New York", 
        "id": "129117340463556"
      }
    }, 
    {
      "id": "dG9waWNfNjU2NDY1NzIyNTE=", 
      "name": "President Bill Clinton", 
      "page": {
        "category": "Public figure", 
        "name": "President Bill Clinton", 
        "id": "65646572251"
      }
    }
  ]
}

Publishing, Deleting, Updating

You can't perform these actions using this edge.