Vue d'ensemble de la recherche

Présentation
- Documentation de l'API Search
Considérations de sécurité
Filtrage avancé

Présentation

L'API Freebase Search permet d'accéder aux données Freebase à partir d'une requête en texte libre. Les résultats de la requête sont triés et présentent un score de pertinence numérique.

Les développeurs peuvent appliquer des filtres pour limiter les résultats de recherche à certains types de données. Pour en savoir plus sur la création de requêtes de recherche détaillées, consultez le Livre de recettes sur la recherche Google.

Voici quelques exemples d'utilisation de l'API Search:

Suggestions automatiques d'entités (par exemple, widget de suggestion Freebase)
Obtenir la liste des entités les plus importantes portant un nom donné
Rechercher des entités à l'aide du métaschéma de recherche

Les exemples de code suivants, disponibles dans plusieurs langages compatibles, montrent comment rechercher un artiste musical correspondant au texte "Cee Lo Green". Une autre contrainte est qu'ils ont créé un contenu appelé "The Lady Killer".

Python

import json
import urllib

api_key = open(".api_key").read()
query = 'blue bottle'
service_url = 'https://www.googleapis.com/freebase/v1/search'
params = {
 'query': query,
 'key': api_key
}
url = service_url + '?' + urllib.urlencode(params)
response = json.loads(urllib.urlopen(url).read())
for result in response['result']:
  print(result['name'] + ' (' + str(result['score']) + ')')

Ruby

require 'rubygems'
require 'cgi'
require 'httparty'
require 'json'
require 'addressable/uri'

API_KEY = open(".freebase_api_key").read()
url = Addressable::URI.parse('https://www.googleapis.com/freebase/v1/search')
url.query_values = {
	'query' => 'Blue Bottle',
	'key'=> API_KEY
}
response = HTTParty.get(url, :format => :json)
response['result'].each { |topic|
  puts topic['name']
}

Cet exemple utilise les bibliothèques Httparty et Addressable.

Java

package com.freebase.samples;

import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.jayway.jsonpath.JsonPath;
import java.io.FileInputStream;
import java.util.Properties;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;

public class SearchExample {
  public static Properties properties = new Properties();
  public static void main(String[] args) {
    try {
      properties.load(new FileInputStream("freebase.properties"));
      HttpTransport httpTransport = new NetHttpTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      JSONParser parser = new JSONParser();
      GenericUrl url = new GenericUrl("https://www.googleapis.com/freebase/v1/search");
      url.put("query", "Cee Lo Green");
      url.put("filter", "(all type:/music/artist created:\"The Lady Killer\")");
      url.put("limit", "10");
      url.put("indent", "true");
      url.put("key", properties.get("API_KEY"));
      HttpRequest request = requestFactory.buildGetRequest(url);
      HttpResponse httpResponse = request.execute();
      JSONObject response = (JSONObject)parser.parse(httpResponse.parseAsString());
      JSONArray results = (JSONArray)response.get("result");
      for (Object result : results) {
        System.out.println(JsonPath.read(result,"$.name").toString());
      }
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

JavaScript

<!DOCTYPE html>
<html>
<head>
    <script src="https://www.gstatic.com/external_hosted/jquery2.min.js"></script>
</head>
<body><aside class="warning"><strong>Warning: </strong>The Freebase API will be retired on June 30,
  2015.</aside>
<script>
  var service_url = 'https://www.googleapis.com/freebase/v1/search';
  var params = {
    'query': 'Cee Lo Green',
    'filter': '(all type:/music/artist created:"The Lady Killer")',
    'limit': 10,
    'indent': true
  };
  $.getJSON(service_url + '?callback=?', params).done(function(response) {
    $.each(response.result, function(i, result) {
      $('<div>', {text:result['name']}).appendTo(document.body);
    });
  });
</script>
</body>
</html>

Cet exemple utilise la bibliothèque jQuery.

PHP

<!DOCTYPE html>
<html>
<body>
<?php
  include('.freebase-api-key');
  $service_url = 'https://www.googleapis.com/freebase/v1/search';
  $params = array(
    'query' => 'Blue Bottle',
    'key' => $freebase_api_key
  );
  $url = $service_url . '?' . http_build_query($params);
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  $response = json_decode(curl_exec($ch), true);
  curl_close($ch);
  foreach($response['result'] as $result) {
    echo $result['name'] . '<br/>';
  }
?>
</body>
</html>

Consultez également la page Bibliothèques clientes pour savoir si votre langage préféré est compatible.

Documentation de l'API Search

Consultez également la documentation suivante:

Pour en savoir plus sur l'utilisation de l'API, consultez les documents de référence sur la recherche.
Pour en savoir plus sur la création de requêtes de recherche détaillées, consultez le Livre de recettes sur la recherche Google.
Pour savoir comment sont décrites les relations entre les entités et les propriétés, consultez le document sur le métaschéma de la recherche.

Considérations de sécurité

L'API Search indexe et recherche le contenu généré par l'utilisateur stocké dans le graphique Freebase. Vous ne pouvez donc pas utiliser le contenu directement sur une page Web sans l'échapper au préalable.

Pour en savoir plus, consultez la section Premiers pas: Sécurité.

Filtrage avancé

L'API Search accepte un grand nombre de contraintes de filtre pour mieux cibler la bonne entité.

Par exemple, en utilisant une contrainte de type "type", nous pouvons afficher une liste des personnes les plus remarquables dans Freebase.

filter=(any type:/people/person)

Les contraintes de filtre acceptent différentes entrées:

ID lisibles pour les entités de schéma ou les utilisateurs, par exemple :
- /people/person pour une contrainte de type
- /film pour une contrainte de domaine
ID MID offerts, par exemple :
- /m/01g317 pour la même contrainte de type /people/person
- /m/010s pour la contrainte de domaine /film ci-dessus
Noms d'entité, par exemple :
- "person" pour une contrainte de type /people/person moins précise
- "film" pour une contrainte de domaine /film moins précise

Les contraintes de filtre peuvent être classées dans plusieurs catégories. Pour en savoir plus, consultez le Guide de recherche.

Vous pouvez combiner et répéter librement des contraintes de filtre directement dans SearchRequest. Les paramètres répétés de contrainte de filtre sont combinés dans une requête OU. Différents paramètres ou groupes de contraintes de filtre sont combinés dans une requête ET.

Exemple :

Pour rechercher des personnes ou des villes nommées Gore, procédez comme suit:

query=gore
&filter=(any type:/people/person type:/location/citytown)

Ce comportement de combinaison peut être remplacé et mieux contrôlé par le paramètre de filtre, qui offre une interface plus riche pour combiner les contraintes. Il s'agit d'une expression s, éventuellement imbriquée de manière arbitraire, où l'opérateur est l'un des suivants:

any, un élément logique OU
all, logiquement un opérateur ET
not
should, qui ne peut être utilisé qu'au niveau supérieur et qui indique que la contrainte est facultative. Lors de l'évaluation, les scores des parties qui ne correspondent pas à des contraintes facultatives sont divisés par deux pour chaque contrainte facultative à laquelle ils ne correspondent pas.

Exemple :

Pour établir une correspondance avec le type /people/person ou le domaine /film, procédez comme suit:

query=gore
&filter=(any type:/people/person domain:/film)