Služba Foursquare si za tři roky své existence vydobyla stěžejní místo mezi uživatelskými LBS (Location-based services). Vznikla pro ní řada aplikací, mj. protože Foursquare od raných počátků nabízel dobře použitelné API. Pojďme si ukázat, jak snadno můžete Foursquare API použít.

Naši aplikaci vytvoříme pro snadnou demonstraci v JavaScriptu, ale můžete ji snadno přepsat prakticky do libovolného programovacího jazyka. Pro její vyzkoušení budete potřebovat účet na Foursquare, který jste alespoň jednou použili (tj. s alespoň jedním čekinem).

Návrh naší aplikace

Jakou aplikaci budeme vytvářet? Vyberme si jednoduché zadání. Takové, kterému se stačí podívat do dat uživatele a zjistí z nich nějakou zajímavou informaci (řada Foursquare aplikací funguje na tomhle principu). V našem případe zkusíme zjistit, na které místo (venue) chodí uživatel nejčastěji (tj. kde má nejvíce čekinů).

Naše aplikace tak bude muset zajistit dva kroky:

1. přihlášení uživatele (autentizace k jeho účtu na Foursquare)
2. získání dat z uživatelovy historie

Přihlášení k Foursquare pomocí Oauth 2.0

K přihlášení uživatele Foursquare používá OAuth 2.0. Ten si zde detailně vysvětlovat nebudeme (o OAuth jsme už dříve psali), do naší aplikace ho implementujeme snadno. Ve stručnosti postačí, když nepřihlášeného uživatele přesměrujeme na URL, kterou nám vygeneruje Foursquare, na té se uživatel přihlásí ke svému Foursquare účtu a je následně přesměrován zpět do naší aplikace. Ta získá přístupový token, který bude následně přikládat ke všem voláním Foursquare API.

Aby celý proces fungoval, musíme naši aplikaci u Foursquare napřed zaregistrovat. To je zdarma a zabere to asi minutu (pozn.: pokud se vám nebude opakovaně dařit vyplnit captchu jako mně, může to zabrat třeba i pět minut).

Na stránce https://foursqu­are.com/oauth/ zvolte Register a new customer a vyplňte formulář (název aplikace, její URL a callback URL, která jsou v našem případě stejná):

Po zaregistrování vám Foursquare vygeneruje client id a client secret. V našem příkladě využijeme pouze client id.

A máme vše k přihlášení našeho uživatele. Stačí, abychom nepřihlášeného uživatele z naší aplikaci přesměrovali na tuto URL (všimněte si, že obsahuje client id a callback url z naší registrace):

window.location.href =
  "https://foursquare.com/oauth2/authenticate?client_id=GTF1A01FTDKKKIQIZV4WRWLRCIFI0YCWEIA10040ECHLEKCF"
  + "&response_type=token"
  + "&redirect_uri=http%3A%2F%2Fukazky.zdrojak.cz%2Ffoursquare%2Ftest.html";

Uživateli se zobrazí přihlašovací/pot­vrzovací dialog:

Pokud jej potvrdí, bude přesměrován na callback url naší aplikace s argumentem access_token=xyz v hash části URL. Ono xyz si uložíme a budeme přidávat ke všem dalším voláním Foursquare API.

Foursquare dokumentace pro vývojáře

Informace pro vývojáře najdete na adrese http://develo­per.foursquare­.com/, popis API pak na http://develo­per.foursquare­.com/docs/.

Nyní se podíváme, jak jak řešit bod dva, tj. najít uživatelovo nejnavštěvova­nější venue.

Projdeme koncové body API (endpointy) a hledáme takový, kterým získáme požadované informace (zvolil jsem naše zadání tak, aby nám stačilo jedno zavolání API, u složitějších aplikací to takhle snadné nebude). Jelikož naše aplikace potřebuje data uživatele, začneme rovnou hledat v sekci users a dříve či později přijdeme na to, že naši úlohu vyřeší jedno zavolání endpointu users – venuehistory. Alternativně bychom mohli naši úlohu vyřešit také pomocí endpointu users – checkins, ale bylo by to komplikovanější (tuhle variantu si můžete vyzkoušet naprogramovat za „domácí úkol“).

Volání nalezeného endpointu si můžete rovnou snadno vyzkoušet v API exploreru (pozn.: možná si ho teď rovnou nevyzkoušíte, v době psaní tohoto článku byl totiž API explorer mimo provoz, ale věřte, že jindy funguje).

Adresa našeho endpointu je https://api.foursquare.com/v2/users/self/venuehistory . Pokud ji ovšem v této podobě zadáte do prohlížeče, získáte tak maximálně chybové hlášení. Co nám chybí? Přístupový token. K URL musíme přidat parametr oauth_token=xyz, kde xyz je token, který jsme si uložili při přihlašování uživatele, pak již vše funguje.

Odpověď serveru je ve formátu JSON a zjednodušeně může vypadat asi takto:

{
  "meta":{"code":200},
  "response":{
    "venues":{
    "count":42,"items":[
       {"beenHere":1,
         "venue":{
            "id":"4adcda9bf964a520a54c21e3",
            "name":"U Malého Glena",
            "stats":{...}
        }
    },
        {...},
        {...}
    ]}
}

Položka meta->code obsahuje stavový kód odpovědi: 200, pokud je vše v pořádku, jinak kód chyby.

Pod response->venues->items najdeme pole s venues, která uživatel navštívil. Každé obsahuje položku beenHere obsahující počet jeho návštěv a následně vlastnosti venue (id, název, statistiky, adresu atd.).

K získání uživatelových dat z Foursquare použijeme následující kód (podle volání $.getJSON můžete poznat, že jsme využili framework jQuery):

$.getJSON("https://api.foursquare.com/v2/users/self/venuehistory?oauth_token=" + oauth + "&v=20120328&callback=?", function(data)
{
    if (data && data.meta && data.meta.code && data.meta.code == 200)
    {
        zpracujData(data.response.venues);
    }
});

Následně projdeme získaná data a vybereme nejnavštěvovanější venue (pro udržení elementárnosti příkladu budeme počítat s tím, že je jen jedno takové):

function zpracujData(venues)
{
    var maxVisits = 0;
    var maxVisitedVenue = null;

    for (var i = 0; i < venues.items.length; i++)
    {
        if (venues.items[i].beenHere > maxVisits)
        {
            maxVisits = venues.items[i].beenHere;
            maxVisitedVenue = venues.items[i];
        }
    }

    if (maxVisitedVenue != null)
    {
        // zobraz uzivateli vysledek:  maxVisitedVenue.venue.name
    }
}

Náměty na rozšíření

• V naší jednoduché aplikaci řešíme přihlášení uživatele plně pomocí Foursquare, v produkční aplikaci bychom nejspíš nechali uživatele se jednou přihlásit pomocí Foursquare, zapamatovali bychom si jeho autorizační token a další přihlašování by již řešila naše aplikace.
• Zkuste aplikaci přepsat do PHP (Pythonu, Ruby, Javy, ASP.NET), aby se komunikace s Foursquare neodehrávala na klientovi, ale na serveru. Nápověda: budete muset upravit volání pro přihlášení uživatele.
• Zkuste celou aplikaci postavit na volání endpointu user-checkins (u aktivních uživatelů budete muset použít opakované volání API).

Jak zrušit autentizaci

V našem případě si aplikace přístupový token nikam na server neukládá, ovšem vygenerovaný token je stále platný. Pokud chcete přístup aplikace do vašeho Foursquare účtu ukončit, zobrazte si stránku https://foursqu­are.com/settin­gs/connections a zvolte Revote Access.