Introdução

A API do Catraca Livre utiliza a plataforma de busca Solr para permitir a consulta por eventos e lugares por uma série de filtros.

A sintaxe para a busca é definida pelo próprio Solr.

Documentação básica da sintaxe: http://wiki.apache.org/solr/SolrQuerySyntax

Documentação da busca por coordenadas geográficas: http://wiki.apache.org/solr/SpatialSearch

Exemplo básico de consulta:

Pesquisar pela palavra ibirapuera no nome do lugar (campo place_name)

http://api.catracalivre.com.br/select/?q=place_name:ibirapuera

Campos

A API do Catraca é dividida em dois núcleos. No núcleo principal cada resultado é apresentado como um documento (<doc>). Há dois tipos de documento (lugares e eventos). Eles são identificados pelo campo post_type, com os valores possíveis sendo "event" ou "place". Já o segundo núcleo permite buscar os eventos por data de ocorrência.

Campos core principal:

  • id: campos de identificação único;
  • post_id: id do post;
  • site_id: id do site dono do post;
  • post_publish_date: data de publicação do post;
  • post_title títulos do post;
  • post_content: conteúdo do post;
  • post_excerpt: resumo do post;
  • post_image_thumbnail: imagem thumbnail do post;
  • post_image_full: imagem do post em tamanho completo;
  • post_permalink: link permanente do post;
  • post_sitecode: identificador de subsite corresponte ao post (sp, rio, bh, etc);
  • post_type: tipo do registro (event ou place);
  • place_type: tipo do lugar (Bar, Restaurante, Parque, Casa de Festas, etc);
  • place_type_slug: slug do tipo de lugar (bar, restaurante, parque, casa-de-festas, etc);
  • place_name: nome do lugar;
  • place_number: número do lugar;
  • place_neighborhood: bairro do lugar;
  • place_zone: zona em que o lugar se encontra (DEPRECATED);
  • place_city: cidade do lugar;
  • place_state: estado do lugar;
  • place_complement: complemento do endereço do lugar;
  • place_cep: CEP do lugar;
  • place_site: site que detém o lugar;
  • place_email: email do lugar;
  • place_phone: telefone do lugar;
  • place_schedule: horário de funcionamento do lugar;
  • place_price: preço de entrada do lugar;
  • place_obs: observações sobre o lugar;
  • place_twitter: usuário twitter do lugar;
  • place_facebook: usuário facebook do lugar;
  • place_googleplus: url do perfil google plus do lugar;
    
  • place_mesoregion: mesoregião do lugar (DEPRECATED);
  • place_accessibility: boleano para determinar se o lugar é acessível ou não;
  • place_street: rua do lugar;
  • place_nearer_train: lugar próximo a transporte por trem;
  • place_nearer_subway: lugar próximo ao metro;
  • place_geolocation: geolocalização do lugares;
  • place_paises.id: id do país correspondente ao lugar;
  • place_estados.id: id do estado correspondente do lugar;
  • place_cidades.id: id da cidade correspondente do lugar;
  • place_bairros.id: id do bairro correspondente do lugar;
  • place_logradouros.id: id do logradouro correspondente do lugar;
  • event_type: tipo de evento;
  • place_id: id do lugar do evento
  • event_datetime: data e hora do evento (multiplos valores);
  • event_time_human: data e hora por extenso (mais amigável);
  • event_agenda: categoria de agenda correspondente ao evento;
  • event_agenda_slug: slug da categoria de agenda do evento;
  • event_price: preço do evento;
  • event_price_numeric: preço número do evento para fins de cálculo;
  • event_place: json descritivo do lugar onde o evento acontece;
  • post_category: categoria do post;
  • post_category_slug: slug da categoria do post;
  • post_site_referrer: json descritivo do site mantenedor do post;

Os campos place_paises.id, place_estados.id, place_cidades.id, place_bairros.id, place_logradouros.id fazem parte da normalização de lugares interna do Catraca Livre, onde cada item de endereço recebeu um ID que permite pesquisas cruzadas e pesquisas territórias mais amplas, orientada a divisão política do país, como por exemplo, todos os lugares do estado de São Paulo. Os nomes estão no plural por mera correspondência com o nome de tabelas usadas internamente pelo Catraca.

Campos do segundo core:

O segundo núcleo da API é chamado chamado "event_time". Para consultar ele, a url http://api.catracalivre.com.br/event_time/select/ deve ser chamada passando os parâmetros de pesquisa. Esse núcleo serve exclusivamente para busca otimizada de eventos por período de data. Por exemplo, você pode pesquisar por um todos os eventos que acontecem entre 20/12/2014 e 30/12/2014 usando a query http://api.catracalivre.com.br/event_time/select/?q=event_datetime:[2014-12-20T00:00:00Z%20TO%202014-12-30T23:59:59Z]. Você receberá como retorno o seguinte conjunto de dados:

  • id: identificador único;
  • post_id: id do post;
  • site_id: site correspondete do post;
  • event_datetime: data e hora de ocorrência do evento;
  • event_time_human: data e hora textual pra melhor apresentação;
  • site_code: código do subsite correspondente ao post;
  • place_id: id do lugar correspondente ao post;

Como esse núcleo é bem menor, ele pode rapidamente retornar um conjunto de dados de posts referentes a um período temporal. Assim, você pode carregar só depois os valores dos posts correspondentes a pesquisa, economizando recurso e otimizando sua aplicação.

Esses são os campos declarados no padrão do schema.xml do solr: http://www.solrtutorial.com/schema-xml.html

Exemplos de consultas

Pesquisar pela palavra ibirapuera

http://api.catracalivre.com.br/select/?q=ibirapuera

Pesquisar pela palavra ibirapuera no nome do lugar (campo place_name)

http://api.catracalivre.com.br/select/?q=place_name:ibirapuera

concatenando dois campos

http://api.catracalivre.com.br/select/?q=post_type:event+AND+post_title=ibirapuera

Pesquisa por coordenadas geográficas (eventos e lugares perto do hacklab)

http://api.catracalivre.com.br/select/?q=*:*&fq={!geofilt%20pt=-23.530,-46.674%20sfield=place_geolocation%20d=3}

Só eventos por coordenadas

http://api.catracalivre.com.br/select/?q=post_type:event*&fq={!geofilt%20pt=-23.530,-46.674%20sfield=place_geolocation%20d=3}

Pesquisa eventos que acontecem dia 30

http://api.catracalivre.com.br/select/?q=event_datetime:[2012-12-30T00:00:00Z%20TO%202012-12-30T23:59:59Z]

Paginação dos resultados

por padrão, é retornado 10 resultados, para mudar isso, passe o parametro &rows=10. Para retornar valores de outras páginas, passe &start=20, ou &start=30..

Apresentando facetas

http://api.catracalivre.com.br/select/?q=*:*&facet=true&facet.field=event_agenda_slug&fl=post_id

Exemplos de implementação

Os exemplos abaixo buscam lugares do tipo cinema em um raio de 3k ao redor de uma coordenada.

Em python

>>> from urllib2 import urlopen
>>> import simplejson
>>> 
>>> conn = urlopen('http://api.catracalivre.com.br/select/?q=place_type_slug:cine*&fq={!geofilt%20pt=-23.5602,-46.6427%20sfield=place_geolocation%20d=3}&fl=place_name&wt=json')
>>> rsp = simplejson.load(conn)
>>> 
>>> rsp
{'responseHeader': {'status': 0, 'QTime': 1, 'params': {'q': 'place_type_slug:cine*', 'fq': '{!geofilt pt=-23.5602,-46.6427
 sfield=place_geolocation d=3}', 'wt': 'json', 'fl': 'place_name'}}, 'response': {'start': 0, 'numFound': 6, 'docs': [{'pla
ce_name': ['CineSesc']}, {'place_name': [u'Cine Clube Pxf3lis']}, {'place_name': [u'Lunetim Mxe1gico']}, {'place_name': [
'Cine Clube Vila Buarque']}, {'place_name': [u'Espaxe7o Itaxfa de Cinema Frei Caneca']}, {'place_name': ['CineSesc']}]}}

Em PHP

php > $res = file_get_contents('http://api.catracalivre.com.br/select/?q=place_type_slug:cine*&fq={!geofilt%20pt=-23.5602,-46.6427%20sfield=place_geolocation%20d=3}&fl=place_name&wt=json');
php > $json = json_decode($res);
php > var_dump($json);
object(stdClass)#1 (2) {
  ["responseHeader"]=>
  object(stdClass)#2 (3) {
    ["status"]=>
    int(0)
    ["QTime"]=>
    int(1)
    ["params"]=>
    object(stdClass)#3 (4) {
      ["fl"]=>
      string(10) "place_name"
      ["q"]=>
      string(21) "place_type_slug:cine*"
      ["wt"]=>
      string(4) "json"
      ["fq"]=>
      string(60) "{!geofilt pt=-23.5602,-46.6427 sfield=place_geolocation d=3}"
    }
  }
  ["response"]=>
  object(stdClass)#4 (3) {
    ["numFound"]=>
    int(6)
    ["start"]=>
    int(0)
    ["docs"]=>
    array(6) {
      [0]=>
      object(stdClass)#5 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(8) "CineSesc"
        }
      }
      [1]=>
      object(stdClass)#6 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(17) "Cine Clube Pólis"
        }
      }
      [2]=>
      object(stdClass)#7 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(15) "Lunetim Mágico"
        }
      }
      [3]=>
      object(stdClass)#8 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(23) "Cine Clube Vila Buarque"
        }
      }
      [4]=>
      object(stdClass)#9 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(35) "Espaço Itaú de Cinema Frei Caneca"
        }
      }
      [5]=>
      object(stdClass)#10 (1) {
        ["place_name"]=>
        array(1) {
          [0]=>
          string(8) "CineSesc"
        }
      }
    }
  }
}