Visão geral da pesquisa

Visão geral
- Documentação da API Search
Considerações sobre segurança
Filtros avançados

Visão geral

A API Freebase Search fornece acesso a dados do Freebase a partir de 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 Manual de pesquisa para ver mais informações sobre como criar consultas de pesquisa detalhadas.

Veja alguns exemplos de como os desenvolvedores podem querer usar a API Search:

Entidades com sugestão automática (por exemplo, widget do Freebase Suggest)
Obter uma lista classificada das entidades mais importantes com um determinado nome.
Como encontrar entidades usando o metaschema de pesquisa.

As seguintes amostras de código em várias linguagens compatíveis mostram como executar uma pesquisa por um artista musical que corresponda ao texto "Cee Lo Green". Uma restrição adicional é que a pessoa 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']
}

Esse 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 ver se sua linguagem favorita é aceita.

Documentação da API Search

Consulte também a documentação abaixo:

Consulte os Documentos de referência de pesquisa para ver detalhes sobre como usar a API.
Consulte o Manual de pesquisa para ver mais informações sobre como criar consultas de pesquisa detalhadas.
Consulte o documento de metaesquema de pesquisa para ver informações sobre como as relações entre entidades e propriedades são descritas.

Considerações sobre segurança

A API Search indexa e pesquisa conteúdo gerado pelo usuário armazenado no gráfico da Freebase. Isso significa que não é possível usar o conteúdo diretamente em uma página da Web sem escapar com segurança antes.

Consulte Primeiros passos: segurança para ver mais informações.

Filtros avançados

A API Search é compatível com várias restrições de filtro para direcionar melhor a pesquisa às entidades corretas.

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

filter=(any type:/people/person)

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

IDs legíveis para entidades de esquema ou usuários, por exemplo:
- /people/person para uma restrição de tipo.
- /film para uma restrição de domínio.
MIDs com base sem custo financeiro, por exemplo:
- /m/01g317 para a mesma restrição de tipo de /people/person
- /m/010s para a restrição de domínio /film acima
Nomes de entidade, 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 Manual de Pesquisa para ver mais detalhes.

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

Exemplo:

Para pesquisar pessoas e cidades chamadas de Gore, tente o seguinte:

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

Esse comportamento de combinação pode ser modificado e melhor controlado com o parâmetro de filtro, que oferece uma interface mais avançada para combinar restrições. É uma expressão s, possivelmente arbitrariamente aninhada, em que o operador é um destes:

any, de maneira lógica, OR
all, de maneira lógica, E
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 correspondem a restrições opcionais têm a pontuação dividida pela metade para cada restrição opcional a que elas não correspondem.

Exemplo:

Para fazer a correspondência com o tipo /people/person ou o domínio /film, tente:

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