Visão geral da pesquisa

  1. Visão geral
  2. Considerações sobre segurança
  3. Filtragem avançada

Visão geral

A API Freebase Search fornece acesso aos dados da Freebase com base em uma consulta de texto livre. Os resultados da consulta são ordenados e têm uma pontuação de relevância numérica.

Os desenvolvedores podem aplicar filtros para restringir os resultados da pesquisa a determinados tipos de dados. Consulte o Livro de receitas de pesquisa para mais informações sobre como criar consultas de pesquisa detalhadas.

Alguns exemplos de como os desenvolvedores podem usar a API Search:

Os exemplos de código a seguir em várias linguagens compatíveis mostram como pesquisar um artista musical que corresponda ao texto "Cee Lo Green". Outra restrição é que ele criou algo chamado "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']
}
Este exemplo usa as bibliotecas Httparty e 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>
 Este exemplo usa a biblioteca 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>

Consulte também a página Bibliotecas de cliente para saber se seu idioma preferido é compatível.

Documentação da API Search

Consulte também a seguinte documentação:

Considerações sobre segurança

A API Search indexa e pesquisa conteúdo gerado pelo usuário armazenado no gráfico do Freebase. Isso significa que não é possível usar diretamente o conteúdo de uma página da Web sem fazer o escape de forma segura primeiro.

Consulte Introdução: segurança para mais informações.

Filtragem avançada

A API Search é compatível com um grande número de restrições de filtro para direcionar melhor a pesquisa às entidades corretas.

Por exemplo, usando uma restrição de filtro "tipo", podemos mostrar uma lista das pessoas mais notáveis na Freebase.

filter=(any type:/people/person)

As restrições de filtro aceitam várias entradas:

  • IDs legíveis para humanos de entidades ou usuários do esquema, por exemplo:
    • /people/person para uma restrição de tipo
    • /film para uma restrição de domínio
  • MIDs do Freebase, por exemplo:
    • /m/01g317 para a mesma restrição de tipo /people/person
    • /m/010s para a restrição de domínio /film acima
  • Nomes de entidades, por exemplo:
    • "person" para uma restrição de tipo /people/person menos precisa
    • "film" para uma restrição de domínio /film menos precisa

As restrições de filtro podem ser classificadas em algumas categorias. Consulte o Cookbook de pesquisa para mais detalhes.

As restrições de filtro podem ser combinadas e repetidas livremente diretamente no SearchRequest. Parâmetros de restrição de filtro repetidos são combinados em uma consulta OR. Diferentes parâmetros ou grupos de restrição de filtro são combinados em uma consulta AND.

Por exemplo:

Para pesquisar "pessoas ou cidades chamadas Gore", tente:

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

Esse comportamento de combinação pode ser substituído e melhor controlado com o parâmetro de filtro, que oferece uma interface mais completa para combinar restrições. É uma expressão S, possivelmente aninhada de forma arbitrária, em que o operador é um dos seguintes:

  • any, logicamente um OR
  • all, logicamente um AND
  • not
  • should, que só pode ser usado no nível superior e indica que a restrição é opcional. Durante a pontuação, as correspondências que não atendem às restrições opcionais têm a pontuação dividida pela metade para cada restrição opcional que não atendem.

Por exemplo:

Para corresponder ao tipo /people/person ou ao domínio /film, tente:

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