Searches

By Public Concepts

When you add an input, it automatically gets predictions from the general model. You can search for those predictions.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search([
{
concept: {
name: 'cat'
}
},
{
concept: {
name: 'dog'
}
}
]).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Custom Concepts

After you have added inputs with concepts, you can search by those concepts.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search([
{
concept: {
type: 'input',
name: 'cat'
}
},
{
concept: {
type: 'input',
name: 'dog'
}
}
]).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Image

You can use images to search through your collection. The API will return ranked results based on how similar the results are to the image you provided in your query.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search(
{
input: {
url: 'https://samples.clarifai.com/puppy.jpg'
}
}
).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Image With Crop

You can search using a crop of an image through your collection. The API will still return ranked results based upon on how similar the results are to the crop of the image you provide in your query.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search(
{
input: {
url: 'https://samples.clarifai.com/puppy.jpg',
crop: [0.1, 0.1, 0.9, 0.9]
}
}
).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Public and Custom Concepts

You can combine a search to find inputs that have concepts you have supplied as well as predictions from your model.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search([
// this is the public concept
{
concept: {
name: 'cat'
}
},
// this is the user-supplied concept
{
concept: {
type: 'input',
name: 'dog'
}
}
]).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Custom Metadata

After you have added inputs with custom metadata, you can search by that metadata.

Below is an example of searching over custom metadata. You can exact match any key: value pair no matter how nested it is. For example, if the metadata on an input is:

{
"keyname": "value1",
"somelist": [1,2,3],
"somenesting": {
"keyname2":"value2",
"list2":[4,5]
}
}

Then the following searches will find this:

{
"keyname": "value1"
}
{
"somelist": [1,2,3]
}
{
"somelist": [1,2]
}
{
"somenesting": {"keyname2":"value2"}
}
{
"somenesting": {"list2":[5]}
}

How to perform searches:

js
python
java
csharp
objective-c
php
cURL
// Search with only metadata
app.inputs.search({
input: {
metadata: {
key: 'value'
}
}
}).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);
// Search with nested metadata
app.inputs.search({
input: {
metadata: {
parent: {
key: 'value'
}
}
}
}).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);
// Search with metadata and concepts or input source
app.inputs.search([
{
input: { metadata: { key: 'value' } }
},
{
concept: { name: 'cat' }
},
{
concept: { type: 'output', name: 'group', value: false }
}
]).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Url

You can also search for an input by URL.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search(
{
input: {
type: 'input',
url: 'https://samples.clarifai.com/puppy.jpg'
}
}
).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

By Geo Location

Search by geo location allows you to restrict your search results to a bounding box based on longitude and latitude points. There are two ways you can provide longitude/latitude points. You can provide one point and a radius or you can provide two points.

It is important to note that a search by geo location acts as a filter and returns results ranked by any other provided search criteria, whether that is a visual search, concept search or something else. If no other criteria is provided, results will return in the order the inputs were created, NOT by their distance to center of the search area.

If you are providing one point and a radius, the radius can be in "mile", "kilometer", "degree", or "radian", marked by keywords withinMiles, withinKilometers, withinDegrees, withinRadians.

If you are providing two points, a box will be drawn from the uppermost point to the lowermost point and the leftmost point to the rightmost point.

Before you perform a search by geo location, make sure you have added inputs with longitude and latitude points.

Add inputs with longitiude and latitude points

Provide a geo point to an input. The geo point is a JSON object consisting of a longitude and a latitude in GPS coordinate system (SRID 4326). There can be at most one single geo point associated with each input.

js
python
java
csharp
objective-c
php
cURL
app.inputs.create({
url: "https://samples.clarifai.com/puppy.jpg",
geo: { longitude: 116.2317, latitude: 39.5427},
}).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

Perform a search with one geo point and radius in kilometers

js
python
java
csharp
objective-c
php
cURL
app.inputs.search({
input: {
geo: {
longitude: 116.2317,
latitude: 39.5427,
type: 'withinKilometers',
value: 1
}
}
}).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

Perform a search with two geo points

js
python
java
csharp
objective-c
php
cURL
app.inputs.search({
input: {
geo: [{
latitude: 116.2316,
longitude: 39.5426
}, {
latitude: 116.2318,
longitude: 39.5428
}]
}
}).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);

Search ANDing

You can also combine searches using AND.

js
python
java
csharp
objective-c
php
cURL
app.inputs.search([
{ input: { url: 'https://samples.clarifai.com/puppy.jpg' } },
{ concept: { name: 'cat', type: 'input' } },
{ concept: { name: 'dog' } }
]).then(
function(response) {
// do something with response
},
function(err) {
// there was an error
}
);