Search by Concept

Search based on specific words

---

You can search for concepts by name, even in a different language, using the ConceptSearches endpoint.

Below is an example of how to search for concepts.

info

The initialization code used in the following example is outlined in detail on the client installation page.

Python

##########################################################################################
# In this section, we set the user authentication, app ID, search name, and language ID.
# Change these strings to run your own example.
##########################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever concept you want to search for
SEARCH_NAME = "人"
LANGUAGE_ID = "ja"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_concepts_searches_response = stub.PostConceptsSearches(
    service_pb2.PostConceptsSearchesRequest(
        user_app_id=userDataObject,
        concept_query=resources_pb2.ConceptQuery(
            name=SEARCH_NAME,
            language=LANGUAGE_ID
        )
    ),
    metadata=metadata
)

if post_concepts_searches_response.status.code != status_code_pb2.SUCCESS:
    print(post_concepts_searches_response.status)
    raise Exception("Post concepts searches failed, status: " + post_concepts_searches_response.status.description)
    
print("Found concepts:")
for concept in post_concepts_searches_response.concepts:
    print("\t%s %.2f" % (concept.name, concept.value))

# Uncomment this line to print the full Response JSON
#print(post_concepts_searches_response)

JavaScript (REST)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, search name, and language ID.
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to whatever concept you want to search for
    const SEARCH_NAME = "人";
    const LANGUAGE_ID = "ja";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "concept_query": [
            {
                "name": SEARCH_NAME,
                "id": LANGUAGE_ID
            }
        ]
    });

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch("https://api.clarifai.com/v2/concepts/searches", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

NodeJS

//index.js file

////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to whatever concept you want to search for
const SEARCH_NAME = "人";
const LANGUAGE_ID = "ja";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PostConceptsSearches(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        concept_query: { name: SEARCH_NAME, language: LANGUAGE_ID }
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("Post concepts searches failed, status: " + response.status.description);
        }

        console.log("Found concepts:");
        for (const concept of response.concepts) {
            console.log("\t" + concept.name + " " + concept.value);
        }
    }
);

Java

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, search name, and language ID.
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication	
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to whatever concept you want to search for
    static final String SEARCH_NAME = "人";
    static final String LANGUAGE_ID = "ja";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiConceptResponse postConceptsSearchesResponse = stub.postConceptsSearches(
            PostConceptsSearchesRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .setConceptQuery(
                ConceptQuery.newBuilder()
                .setName(SEARCH_NAME)
                .setLanguage(LANGUAGE_ID))
            .build()
        );

        if (postConceptsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post concepts searches failed, status: " + postConceptsSearchesResponse.getStatus());
        }

        System.out.println("Found concepts:");
        for (Concept concept: postConceptsSearchesResponse.getConceptsList()) {
            System.out.printf("\t%s %.2f%n", concept.getName(), concept.getValue());
        }

    }

}

PHP

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// Change these strings to run your own example.
///////////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to whatever concept you want to search for
$SEARCH_NAME = "人";
$LANGUAGE_ID = "ja";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\PostConceptsSearchesRequest;
use Clarifai\Api\ConceptQuery;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostConceptsSearches(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostConceptsSearchesRequest([
        "user_app_id" => $userDataObject,        
        "concept_query" => new ConceptQuery([
            "name" => $SEARCH_NAME,
            "language" => $LANGUAGE_ID
        ])
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

echo "Found concepts: </br>";
foreach ($response->getConcepts() as $concept) {
    echo $concept->getName() . ": " . number_format($concept->getValue(), 2) . "</br>";
}

?>

cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_query": {
      "name":"人",
      "language": "ja"
    }
  }'

Code Output Example

Found concepts:
    人 1.00
    人 1.00

JSON Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "6e24dbc1e4977bd6f4092d0c72169a68"
  }
  concepts {
    id: "ai_ZKJ48TFz"
    name: "\344\272\272"
    value: 1.0
    created_at {
      seconds: 1458214981
      nanos: 223962000
    }
    language: "ja"
    app_id: "main"
    visibility {
      gettable: PUBLIC
    }
    user_id: "clarifai"
  }
  concepts {
    id: "ai_l8TKp2h5"
    name: "\344\272\272"
    value: 1.0
    created_at {
      seconds: 1458214981
      nanos: 223962000
    }
    language: "ja"
    app_id: "main"
    visibility {
      gettable: PUBLIC
    }
    user_id: "clarifai"
  }