[Resolvido] Criando um aplicativo para Foursquare usando PHP

[RSS iMasters 5]

Os serviços baseados em localização, como o Fourquare,estão totalmente na moda. Parece que, para qualquer lugar que você olhe, as pessoas estão usando Foursquare, Gowalla, Loopt e outras ferramentas para "efetuarem o registro de entrada" em seus locais favoritos. Estas ferramentas ainda compartilham dicas com outros usuários sobre bebidas e pratos favoritos além de toda essa atividade em outros serviços como o Twitter e o Facebook.

 

Como desenvolvedor, você deve saber sobre tudo isso. Os serviços sociais e, especificamente, os serviços baseados em local que usam plataformas sociais representam uma grande área de crescimento para desenvolvedores da Web e de dispositivos remotos.

 

A maioria desses serviços usa algum tipo de serviço RESTful, que você pode usar para solicitar JavaScript Serialized Object Notation (JSON) ou dados XML. Alguns, como o Facebook, não exigem muita autenticação, enquanto outros, como o Foursquare, possuem algumas alimentações que exigem autenticação e outras que não.

 

Para os fins deste artigo, presumirei que você sabe alguma coisa sobre PHP. Veremos aqui como acessar uma alimentação de Foursquare, trabalhando através do conjunto de resultados e limpando-o.

 

O aplicativo de amostra que você construirá ao final deste artigo é simples: fornecer Foursquare com coordenadas geolat e geolong e ver quantas pessoas estão atualmente registradas em locais vizinhos. Como moro em Austin, no Texas, acho que seria interessante inserir coordenadas de um local na Sixth Street e ver o que está acontecendo por lá.

 

Escolhi essa opção em particular por dois motivos. O primeiro é porque ela é a alimentação mais simples de acessar, mas desenvolvê-la oferece uma boa ideia daquilo que você pode esperar com outras alimentações. O segundo é que ela não requer autenticação - afinal de contas, você não está procurando detalhes sobre quem realmente está registrado, são contas estimadas.

 

A alimentação pública de pontos de encontro oferece grande funcionalidade dentro do escopo deste artigo.

 

 

O que é o Foursquare?

O Foursquare é um serviço social de local que permite que os usuários explorem o mundo ao seu redor. Os usuários podem fazer o download do aplicativo Foursquare para o iPhone, Blackberry ou Android, inscrever-se grátis e depois conectar suas contas do Foursquare a outras contas de mídia social.

 

Depois que os usuários fizerem o download do aplicativo grátis e se conectarem ao Facebook ou Twitter, eles não podem se conectar com os amigos que também estão ativos no Foursquare.

 

Sempre que os usuários ou seus amigos se conectarem a um local (ou seja, eles estão em um local e querem que os outros saibam que estão lá), a mensagem é transmitida aos seus amigos através do Twitter ou Facebook.

 

Quando um usuário efetua o registro de entrada vezes suficientes, o usuário se torna oprefeito de um local, que pode ou não oferecer acesso de usuário para ofertas especiais, dependendo do negócio que está sendo administrado no local. Por exemplo, uma cafeteria pode oferecer uma bebida grátis para aqueles que se tornarem prefeitos.

 

Os usuários também podem ganhar badges conforme exploram e efetuam o registro de entrada em locais, deixam dicas para outros usuários (por exemplo, "As margueritas aqui são ótimas!"), e podem até ter a oportunidade de criar locais que ainda não apareceram no serviço.

 

A figura 1 é uma captura de tela da página inicial do Foursquare na Web.

 

Figura 1. Página inicial do Foursquare

 

 

O Foursquare lançou sua API em novembro de 2009, permitindo que os desenvolvedores de aplicativos estendessem a plataforma de formas interessantes.

 

Os desenvolvedores podem construir ferramentas de gerenciamento de local, mecanismos de procura customizados e até mesmo jogos e outras ferramentas que interajam com a API do Foursquare.

 

Por exemplo, é possível construir um jogo geolocation que permite que os jogadores também se conectem a locais do Foursquare como um subproduto natural do gameplay normal.

 

Tendo essa visão do Foursquare em mente, vamos dar uma olhada na API do Foursquare.

 

 

Um tour rápido pela API do Foursquare

A API do Foursquare permite que os desenvolvedores de aplicativos interajam com a plataforma Foursquare. A API em si é um conjunto RESTful de endereços para os quais é possível enviar solicitações, então não há realmente nada para ser transferido por download para o seu servidor.

 

Dito isso, neste artigo usamos um conjuntos de bibliotecas PHP para ajudar a simplificar solicitações e respostas, mas essa é uma etapa inteiramente opcional.

 

Atualmente é possível solicitar saída em formato XML ou JSON, fazendo solicitações para URLs parecidas com esta: http://api.foursquare.com/v1/user.json'>http://api.foursquare.com/v1/user.json.

 

Se você não usar uma extensão na sua solicitação, o XML é retornado para você. Uma solicitação para http://api.foursquare.com/v1/user resultados em uma saída XML.

 

Há os métodos GET e POST que podem ser usados, o que significa que você não está limitado a apenas ler a partir de alimentações, também é possível fazer coisas úteis, como efetuar o registro de entrada e criar locais usando a API.

 

Em relação aos limites de taxa, seu aplicativo é limitado a 200 solicitações por hora por método, de modo que você provavelmente irá querer implementar algum tipo de armazenamento em cache dos resultados para "fazer uma boa jogada".

 

Em relação à maioria, você quer usar autenticação básica ou OAuth para aproveitar ao máximo os vários métodos e serviços. O exemplo neste artigo (/venues) não requer nenhuma autenticação para ser iniciado, mas possui recursos adicionais disponíveis para aqueles que usam autenticação.

 

O que é possível fazer com a API? A tabela 1 resume os métodos principais. Parta obter mais detalhes, leia a documentação da API.

 

Tabela 1. Resumo dos métodos de API do Foursquare

 

MétodoResumoURLParâmetrosMétodo(s) HTTPAutenticação?CheckinsRetorna uma lista de registros de entrada recentes de amigos.http://api.foursquare.com/v1/checkinsgeolat, geolongGETSimCheckinPermite que você efetue o registro de entrada em um local.http://api.foursquare.com/v1/checkinvid, venue, geolat, geolong (outros)POSTSimHistóricoRetorna uma lista de registros de entrada do usuário autenticado.http://api.foursquare.com/v1/historyl, sinceidGETSimDetalhes do usuárioRetorna informações de perfil de um dado ID do usuário.http://api.foursquare.com/v1/useruid, twitter, badges, mayorGETSimAmigosRetorna uma lista de amigos.http://api.foursquare.com/v1/friendsuidGETSimPontos de encontroRetorna uma lista de pontos de encontro perto da área especificada.http://api.foursquare.com/v1/venuesgeolat, geolong, l, qGETNãoDetalhes do ponto de encontroRetorna dados de ponto de encontro de um dado ID de ponto de encontro.http://api.foursquare.com/v1/venuevidGETNãoCategoriasRetorna uma lista de categoria hierárquicahttp://api.foursquare.com/v1/categoriesnão disponívelGETNãoAdicionar ponto de encontroPermite que você adicione um ponto de encontro.http://api.foursquare.com/v1/addvenuename, address, city, state, zip, phone, geolat, geolong, othersPOSTSimPropor edição de ponto de encontroPermite que você sinalize um ponto de encontro para editar ou atualizar.http://api.foursquare.com/v1/venue/proposeeditvid, name, address, city, state, zip, phone, geolat, geolong, outrosPOSTSimHá um monte de outros métodos de API que se relacionam a amigos, teste de autenticação, sinalização de locais por diferentes motivos, coleta e criação de dicas, etc., mas acho que você pegou a ideia geral.

 

 

Construindo seu próprio aplicativo PHP

Agora que você fez o seu pequeno tour pela API do Foursquare, é possível voltar ao negócio e construir um aplicativo simples.

 

Como sugeri na introdução, o que pretendo fazer é criar uma visualização que me diga quantas pessoas se registraram em locais centrados ao redor dos bares da Sixth Street em Austin. Afinal de contas, não faz sentido dirigir até o centro e encontrar um lugar para estacionar se ninguém estiver por lá!

 

Embora possa parecer um pouco frívolo usar a API do Foursquare para esse propósito, observe que é possível pegar a ideia básica e usá-la em uma variedade de contextos.

 

Por exemplo, é possível controlar quantos participantes da conferência estão se registrando nos pontos de encontro locais enquanto estão na cidade ou quantas pessoas estão registradas em várias sessões de lançamento de conferência.

 

Para os fins deste artigo, divido o processo em três partes principais:

 

1. Fazer o download de bibliotecas auxiliares
2. Criar uma alimentação básica
3. Criar uma página da Web limpa com o conteúdo da alimentação

Faça o download da biblioteca foursquare-async

Embora você realmente não precise de muito wrapper para a API do Foursquare, é uma boa ideia fazer o download da maravilhosa biblioteca foursquare-async a partir do GitHub. Ele fornece muitos arquivos que permitem que você trabalhe com a maioria dos métodos disponíveis para você através da API.

 

O download inclui um arquivo leia-me, um documento de licença e três arquivos PHP:

 

• EpiCurl.php

• EpiFoursquare.php

• EpiOAuth.php

Coloque todos os três arquivos PHP em um diretório chamado lib na raiz do seu projeto e vá para a etapa seguinte na construção do aplicativo.

 

 

Criar uma alimentação

Em seguida, crie um arquivo chamado feed.php e coloque-o na raiz do seu projeto. Nesse arquivo, você usa a função require() para puxar todos os arquivos Epi*.php que foram transferidos por download e colocá-los na pasta lib.

 

Depois instancie um objeto epiFourSquare e use esse objeto para se conectar à alimentação de venues.json, passando quaisquer parâmetros necessários para geolat, geolong, e um limite de 50 resultados.

 

Finalmente, use json_encode() para transformar a alimentação JSON recebida em um objeto de dados PHP e salvá-la como array. É claro que para estar seguro sobre tudo isso, você deve quebrar a coisa toda em try {...}exception.

 

Se você não executar a alimentação através de json_encode(), acabará processando algo como a alimentação mostrada abaixo.

 

Figura 2. Alimentação JSON bruta

 

 

Para muitos ela está boa, mas você tem que admitir que o objeto de dados PHP mostrado na figura 3 é um pouco mais fácil de entender.

 

Figura 3. Objetos de dados PHP do JSON

 

 

A listagem 1 mostra o fragmento inteiro do código.

 

Listagem 1. Conexão à alimentação de pontos de encontro do Foursquare

 

require('lib/EpiCurl.php');

require('lib/EpiOAuth.php');

require('lib/EpiFoursquare.php');

 

$fsObj = new EpiFoursquare();

try{

$venues = $fsObj->get_basic('/venues.json',

array('geolat' => '30.268056',

'geolong' => '-97.741381',

'l' => '50'));

 

$venues_array = json_decode($venues->responseText);

 

}catch(Exception $e){

echo "Error: ". $e;

}Isso não é nada muito complexo, apenas 15 linhas de código para obter uma alimentação de pontos de encontro e contagens de registros de entrada. Observe que as coordenadas geolat e geolong no exemplo correspondem aos arredores do Hotel Driskill no centro de Austin - Estou usando esse local como um ponto central prático, já que muitos pontos de encontro no centro são próximos a ele.

 

 

Criar uma visualização da Web

Nesse ponto, o que você tem é uma alimentação JSON que foi convertida para um objeto de dados PHP. Isso é útil para o programador de PHP, mas quase inútil para as demais pessoas. O que você precisa é colocar tudo isso em uma página da Web que meros mortais possam usar.

 

Para esse fim, crie um arquivo index.php na raiz do seu diretório. Use qualquer elemento de estrutura e design das Cascading Style Sheets (CSS) e do JavaScript com os quais se sentir à vontade.

 

Por exemplo, observe no código de amostra mostrado na listagem 2 que eu uso a estrutura 960 Grid porque ela torna meu trabalho mais fácil. Inclua também o código feed.php que acabou de escrever e depois processo a array $venues_array para que se ajuste à tabela de dados.

 

A parte complicada é que a API do Foursquare é hierárquica, sendo que o primeiro nível (grupos) é muito significativo para você. É preciso acesso ao nível de pontos de encontro, porque é aí que você vai fazer o loop e extrair informações valiosas para uso posterior.

 

Parte do exemplo mostrado na listagem 2 fornece uma forma abreviada que faz isso: foreach ($venues_array->groups[0]->venues como $v){ inicia o loop no local correto no objeto de dados PHP e permite acessar itens como $v->name para nome de ponto de encontro e $v->stats->herenow para o número de pessoas atualmente registradas no ponto de encontro.

 

De fato, se você visualizar a estrutura de dados de $v toda vez através do loop, ela se parece um pouco com a listagem 2.

 

Listagem 2. Objeto de dados PHP para cada ponto de encontro

 

stdClass Object

{

[id] => 5261

[name] => Driskill Hotel

[primarycategory] => stdClass Object

{

[id] => 79273

[fullpathname] => Travel:Hotel

[nodename] => Hotel

[iconurl] => http://foursquare.com/img/categories/travel/hotel.png

}

 

[address] => 604 Brazos St

[crossstreet] => at W 6th St

[city] => Austin

[state] => TX

[zip] => 78701

[geolat] => 30.2679601

[geolong] => -97.7413707

[stats] => stdClass Object

{

[herenow] => 0

}

 

[phone] => 5124745911

[distance] => 0

}O fragmento de código na listagem 3 fornece toda a página index.php, completa, com um loop através da estrutura de dados, extraindo as partes relevantes para uma array $final, que depois é usada para criar uma tabela de dados.

 

O resultado é um painel que mostra o nome do ponto de encontro, o endereço e número de telefone e quantas pessoas estão registradas lá.

 

Observe também que, devido ao fato de o número de telefone não ser um campo obrigatório para um ponto de encontro, você deve executar uma rápida verificação para ver se foi incluído na alimentação de dados. Se sim, imprima o número, se não, omita-o.

 

Listagem 3. Construção da visualização index.php

 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />

<title>FourSquare API Test</title>

<link rel="stylesheet" type="text/css" href="css/960.css" media="all" />

<link rel="stylesheet" type="text/css" href="css/reset.css" media="all" />

<link rel="stylesheet" type="text/css" href="css/text.css" media="all" />

<link rel="stylesheet" type="text/css" href="css/tables.css" media="all" />

 

 

</head>

<body>

<div class="container_12">

<div class="grid_12">

<h1>FourSquare API Test</h1>

</div>

</div>

 

 

<div class="container_12">

<div class="grid_12" id="updates">

<?php

include_once 'feed.php';

$final = array();

 

foreach ($venues_array->groups[0]->venues as $v){

if (isset($v->phone)){

$PHONE = $v->phone;

}else{

$PHONE = "not listed";

}

 

$final[$v->id] = array(

'name' => $v->name,

'address' => $v->address,

'herenow' => $v->stats->herenow,

'phone' => $PHONE

);

 

}

 

?>

 

<table border='1' cellspacing='0' cellpadding='0'>

<thead>

<tr valign='top'>

<th>Location</th>

<th>Address</th>

<th>Phone</th>

<th>Here Now</th>

</tr>

</thead>

<tbody>

<?php

foreach ($final as $key => $data){

echo "<tr valign='top'>";

echo "<td>".$data['name']."</td>\n";

echo "<td>". $data['address']."</td>\n";

echo "<td>". $data['phone']."</td>\n";

echo "<td align='center'>". $data['herenow']."</td>\n";

echo "</tr>\n";

}

?>

</tbody>

</table>

 

</div>

</div>

</body>

</html>A maior parte do código de exemplo por trás do PHP é apenas para oferecer uma boa aparência para as pessoas e não é necessariamente funcional. É possível aplicar seus próprios estilos e abordagens para tornar as informações visualmente coerentes.

 

Por exemplo, é possível vincular a alimentação JSON do arquivo PHP a um método jQuery.getJSON() para que ela possa ser atualizada sem necessidade de atualizar a página da Web.

 

Também é possível usar uma lista mais simples e direta para apresentar as informações, de modo que pareçam mais naturais dentro do contexto de uma tela limitada de smartphone. Por exemplo, a listagem 4 mostra o loop final foreach, gerando uma lista.

 

Listagem 4. Listagem simplificada

 

?>

 

<ul>

<?php

foreach ($final as $key => $data){

echo "<li>";

echo $data['name']." (". $data['herenow'].")". "<br/>\n";

echo $data['address']."<br/>\n";

echo $data['phone']."<br/>\n";

echo "</li>\n";

}

?>

</ul>Simplesmente adicionar algumas classes aos nós UL e LI já cria uma experiência visual tentadora para qualquer um que esteja usando um iPhone ou outro dispositivo remoto. Elas podem verificar sua página da Web, ver o que está acontecendo nos locais ao redor das coordenadas específicas geolat/geolong e decidir para onde ir à noite.

 

O que mais é possível fazer para melhorar a experiência do usuário? Peça a um usuário para se autenticar no Foursquare para ver mais detalhes.

 

Os detalhes sobre como fazer isso estão além do escopo deste artigo, mas quando usuários são autenticados, é possível fornecer ainda mais informações sobre seus amigos específicos nessa lista.

 

Também é possível fornecer uma interface de mapa simples para permitir que os usuários escolham uma coordenada geolat/geolong com a qual começar, tornando-a uma ferramenta mais útil no geral.

 

 

Conclusão

Agora que você sabe como usar a API do Foursquare, é sua vez de criar algo interessante. No entanto, antes de se aprofundar muito, verifique o que os outros estão fazendo com a API. A App Gallery do Foursquare contém alguns aplicativos notáveis criados por outras pessoas.

 

 

Recursos

Aprender

 

• Participe do Foursquare.
• Leia a documentação da API do Foursquare.
• Visite a App Gallery do Foursquare para ver outros aplicativos que foram construídos com a API do Foursquare.
• PHP.net é o recurso central para desenvolvedores de PHP
• Confira a "Lista de leitura recomendada sobre PHP."
• Navegue pelo conteúdo de PHP no developerWorks.
• Amplie suas qualificações verificando os recursos de projeto de PHP do IBM developerWorks.
• Você está usando um banco de dados com PHP? Confira o Zend Core para IBM, um ambiente de produção e desenvolvimento de PHP contínuo, fácil de instalar e pronto para uso que suporta IBM DB2 V9.
• A comunidade My developerWorks é um exemplo de comunidade geral bem-sucedida que abrange uma ampla variedade de tópicos.
• Acompanhe e aprenda sobre a IBM e tecnologias de software livre e funções de produto com as demos gratuitas on demand do developerWorks.

Obter produtos e tecnologias

 

• Faça o download da biblioteca foursquare-async.

***

 

artigo publicado originalmente no developerWorks Brasil, por Thomas Myer

 

 

Thomas Myer é um consultor, autor e palestrante que mora em Austin. Ele dirige a Triple Dog Dare Media e pode ser encontrado como @myerman no Twitter. É possível entrar em contato com ele através do e-mail tom@tripledogs.com.

 

 

 

http://imasters.com.br/artigo/19440/php/criando-um-aplicativo-para-foursquare-usando-php/