Criando um aplicativo para Foursquare usando PHP

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.

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étodo	Resumo	URL	Parâmetros	Método(s) HTTP	Autenticação?
Checkins	Retorna uma lista de registros de entrada recentes de amigos.	http://api.foursquare.com/v1/checkins	geolat, geolong	GET	Sim
Checkin	Permite que você efetue o registro de entrada em um local.	http://api.foursquare.com/v1/checkin	vid, venue, geolat, geolong (outros)	POST	Sim
Histórico	Retorna uma lista de registros de entrada do usuário autenticado.	http://api.foursquare.com/v1/history	l, sinceid	GET	Sim
Detalhes do usuário	Retorna informações de perfil de um dado ID do usuário.	http://api.foursquare.com/v1/user	uid, twitter, badges, mayor	GET	Sim
Amigos	Retorna uma lista de amigos.	http://api.foursquare.com/v1/friends	uid	GET	Sim
Pontos de encontro	Retorna uma lista de pontos de encontro perto da área especificada.	http://api.foursquare.com/v1/venues	geolat, geolong, l, q	GET	Não
Detalhes do ponto de encontro	Retorna dados de ponto de encontro de um dado ID de ponto de encontro.	http://api.foursquare.com/v1/venue	vid	GET	Não
Categorias	Retorna uma lista de categoria hierárquica	http://api.foursquare.com/v1/categories	não disponível	GET	Não
Adicionar ponto de encontro	Permite que você adicione um ponto de encontro.	http://api.foursquare.com/v1/addvenue	name, address, city, state, zip, phone, geolat, geolong, others	POST	Sim
Propor edição de ponto de encontro	Permite que você sinalize um ponto de encontro para editar ou atualizar.	http://api.foursquare.com/v1/venue/proposeedit	vid, name, address, city, state, zip, phone, geolat, geolong, outros	POST	Sim

Há 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:

Fazer o download de bibliotecas auxiliares
Criar uma alimentação básica
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.

De 0 a 10, o quanto você recomendaria este artigo para um amigo?