Poznaj Yahoo! API

Firma Yahoo! udostępnia programistom aplikacji internetowych zestaw usług określanych jako Yahoo API. Pozwalają one na dostęp do zasobów Yahoo z poziomu aplikacji. W ten sposób możemy np. przygotować własną wyszukiwarkę lub zbadać linki zwrotne przychodzące do serwisu.

Usługi grupy Yahoo! Search Web Services
pozwalają na przeszukiwanie zasobów
WWW skatalogowanych przez wyszukiwarkę
należącą do portalu Yahoo! Wyszukiwanie
może być ukierunkowane na konkretne zasoby
multimedialne (Audio Search, Image Search oraz
Video Search) lub na nowości (News Search).
Dodatkowo usługa Site Explorer pozwala poznać
linki skierowujące, wskazujące na wybraną
witrynę oraz zestaw skatalogowanych podstron
witryny.

Szczegółowe informacje o usługach Yahoo!
Search Web Services są dostępne na stronie
http://developer.yahoo.com/search/.
Wymienione usługi Yahoo! API są bezpłatne zarówno
do zastosowań prywatnych, jak i komercyjnych.
Każda aplikacja może wykonywać dziennie
5000 tysięcy zapytań z jednego adresu IP. Po
przekroczeniu tego ograniczenia, dostęp do usługi
zostaje zablokowany do następnego dnia.
Korzystając z usług Yahoo, należy przestrzegać
następujących ograniczeń:

• każda aplikacja korzystająca z Yahoo API powinna
  zawierać link zwrotny informujący o wykorzystaniu
  usług Yahoo,
• aplikacja nie może korzystać z usług innych
  dostawców API do przeszukiwania zasobów
  WWW,
• nie można tworzyć metawyszukiwarek, pozwalających
  na wyszukiwanie danych u kilku
  dostawców,
• nie można omijać limitów dotyczących liczby
  zapytań.

Interfejs

Usługi Yahoo! API są udostępniane w trybie
REST jako zestaw adresów URL. Każda z usług
ma ustalony adres URL oraz określony zestaw
parametrów. W ten sposób interfejs jest niezależny
od platformy sprzętowo-programowej oraz języka
programowania.

Na przykład usługa wyszukiwania w sieci
WWW posiada adres URL:

http://search.yahooapis.com/WebSearchService/V1/contextSearch

i przykładowe parametry:

• appid – identyfikator aplikacji
• query – szukany ciąg
• results – liczba zwracanych wyników

Wyszukanie adresów stron dotyczących frazy
\”owoce\” sprowadzi się do pobrania dokumentu
o adresie:

http://search.yahooapis.com/WebSearchService/V1/contextSearch?appid=...&query=owoce&results=75

Odpowiedź Yahoo może być zapisana w formacie
XML, JSON lub PHP. W języku PHP wystarczy
wywołać dwie funkcje, {stala}file_get_contents(){/stala} oraz
{stala}unserialize(){/stala}:

$adr =\'http://search.yahooapis.com/WebSearchService/\'.\'V1/contextSearch?appid=...&query=owoce&results=75\'
$p = file_get_contents($adr);
$t = unserialize($p);

i będziemy już dysponowali tablicą asocjacyjną
zawierającą wyniki zwrócone przez Yahoo.

Rozpoczynamy pracę

Korzystanie z Yahoo! API rozpoczynamy od
rejestracji. Następnie przechodzimy do wygenerowania
identyfikatora aplikacji. Każda aplikacja powinna
posiadać unikalny identyfikator podawany
w zapytaniach URL jako parametr appid.
Wszystkie wygenerowane identyfikatory aplikacji
możemy przeglądać panelem administracyjnym.

Usługa Web Search

Usługa WebSearch, opisana na stronie http://developer.yahoo.com/search/web/, jest dalej
podzielona na cztery podusługi:

• Context Search – wyszukiwanie kontekstowe,
• Related Suggestion – wyszukiwanie fraz zbliżonych do podanej frazy,
• Spelling Suggestion – wskazówki dotyczące pisowni podanej frazy,
• WebSearch – wyszukiwanie zasobów w sieci WWW.

Do wyszukiwania zasobów w sieci WWW należy
oczywiście wykorzystać ostatnią z wymienionych
usług, tj. WebSearch (jej nazwa jest taka sama, jak
nazwa grupująca wymienione cztery podusługi).
Adresem URL usługi WebSearch jest:
http://search.yahooapis.com/WebSearchService/V1/contextSearch
Jej parametry są zawarte w tabeli 1(w załączniku).

Usługa ta pozwala na wyszukiwanie zasobów w sieci
WWW. Obowiązkowymi parametrami są appid
oraz query. Pozostałe parametry są opcjonalne.
Wyniki zwracane w formacie XML są zgodne ze
schematem XSD, dostępnym pod adresem:
http://search.yahooapis.com/WebSearchService/V1/WebSearchResponse.xsd.

Zawierają one zestaw danych (element ResultSet) podzielony na poszczególne wyniki
wyszukiwania (elementy Result):

...
...

...
...
...

Do przetestowania usługi możemy wykorzystać
skrypt przedstawiony na listingu 1.

Podając parametr {stala}output=php{/stala}, otrzymamy wyniki
w formacie zserializowanej tablicy asocjacyjnej
PHP. Wywołując funkcję {stala}unserialize(){/stala}, dostaniemy
tablicę asocjacyjną. W ten sposób nie będzie
zachodziła konieczność parsowania dokumentu
XML. Przykład przedstawiający takie rozwiązanie
jest przedstawiony na listingu 2.

\';
var_dump($p);
echo \'

\’;
?>

Usługa Site Explorer

Usługa ta jest podzielona na cztery podusługi:

• Inlink Data – wyszukiwanie linków zwrotnych,
• Page Data – badanie, które podstrony serwisu
  zostały zaindeksowane przez Yahoo,
  Pink oraz Update Notification – informowanie
  Yahoo o zmianach w serwisie.

Usługa do badania linków zwrotnych, Inlink
Data, jest dostępna pod adresem:
http://search.yahooapis.com/SiteExplorerService/V1/inlinkData
Tabela 2 (w załączniku) zawiera zestawienie parametrów.
Listing 3 demonstruje, w jaki sposób sprawdzić
linki wskazujące na adres gajdaw.pl z pominięciem
linków z domeny gajdaw.pl.

\';
var_dump($p);
echo \'

\’;
?>

Wyniki zwracane w formacie XML zawierają
elementy:

...

...
...

i są zgodne ze schematem XSD dostępnym pod
adresem:
http://search.yahooapis.com/SiteExplorerService/V1/InlinkDataResponse.xsd

Obiektowa implementacja dostępu do usług Yahoo

Klasa YahooAPI

Implementując obiektowy interfejs dostępu
do usług Yahoo, najpierw przygotowujemy klasę
bazową YahooAPI przedstawioną na listingu 4.

{
protected $appurl;
protected $parameters;
protected abstract function setAppUrl();
protected abstract function setDefaults();
public function __construct($appid)
       {
       $this->setAppUrl();
       $this->setDefaults();
       $this->setParameter(\'appid\',$appid);
       $this->results = false;
       }
public function setParameter($name,$value)
       {
       $this->parameters[$name] =$value;
       }
public function getParameter($name)
       {
       if (isset($this->parameters[$name])) {
       return $this->parameters[$name];
       } else {
       return false;
       }
}
public function getQueryUrl()
{
 $this->queryUrl =$this->appurl . \'?\' .http_build_query($this->parameters);
 return $this->queryUrl;
}
public function doSearch()
{
 $p = @file_get_contents($this->getQueryUrl());
 if ($p) {
 if ($this->getParameter(\'output\') == \'php\') {
 $this->results = unserialize($p);
} else {
  $this->results = $p;
  }
  return $this->results;
} else {
  $this->results = false;
  return $this->results;
  }
}
}

Klasa ta odpowiada za konstruowanie adresów
URL, wysyłanie zapytań, odbieranie wyników
i deserializację danych.

Parametrem konstruktora jest identyfikator aplikacji.
Klasy potomne muszą implementować dwie
metody abstrakcyjne {stala}setAppUrl(){/stala} oraz {stala}setDefaults(){/stala}.
Pierwsza z nich ustala adres URL konkretnej
usługi, zaś druga definiuje domyślne parametry.
Dodatkowe parametry każdej usługi definiujemy,
wywołując metodę {stala}setParameter(){/stala}.

Klasa YahooSearch

Klasa YahooSearch (listing 5) dziedziczy po
klasie YahooAPI.

{
protected function setAppUrl()
{
  $this->appurl = \'http://search.yahooapis.com/WebSearchService/V1/webSearch\';
}
protected function setDefaults()
{
  $this->parameters = array(\'language\' => \'pl\',\'results\' => 5,\'output\' => \'php\');
}
public function getParsedResults($query)
{
 $this->setParameter(\'query\',rawurlencode($query));
 $this->doSearch();
 if ($this->results) {
return $wyniki = $this->results[\'ResultSet\'][\'Result\'];
       } else {
       return array();
}
}
}

Pokryte metody {stala}setAppUrl(){/stala} oraz
{stala}setDefaults(){/stala} ustalają parametry usługi, zaś metoda
{stala}getParsedResults(){/stala} zwraca wyniki wyszukiwania.
Użycie klasy sprowadza się do wywołania
konstruktora oraz metody {stala}getParsedResults(){/stala}. Dodatkowe
parametry wyszukiwania możemy ustalić
metodą {stala}setParameter(){/stala}:

$ys = new YahooSearch(MJ99...);
$ys->setParameter(\'language\', \'pl\');
$wyniki = $ys->getParsedResults(\'pomidor\');

Klasa YahooInboundLinks

Klasa YahooInboundLinks ułatwia wyszukiwanie
linków zwrotnych. Została ona przedstawiona
na listingu 6.

{
      protected function setAppUrl()
{
      $this->appurl = \'http://search.yahooapis.com/SiteExplorerService/V1/inlinkData\';
}
      protected function setDefaults()
{
      $this->parameters = array(\'omit_inlinks\' => \'domain\',\'results\' => 100,\'output\' => \'php\',);
}
 public function getParsedResults($query)
{
        $this->setParameter(\'query\', rawurlencode($query));
        $this->doSearch();
        if ($this->results) {
           if ($this->results[\'ResultSet\'][\'totalResultsReturned\'] == 1) {
           return array($this->results[\'ResultSet\'][\'Result\']);
           } else if ($this->results[\'ResultSet\'][\'totalResultsReturned\'] > 1) {
           return $this->results[\'ResultSet\'][\'Result\'];
            } else {
        return array();
}
        } else {
        return array();
}
}
}

Przykładowe użycie przyjmie postać:

$yin = new YahooInboundlinks(\'MJ99W...\');
$yin->setParameter(\'results\', 5);
$wyniki = $yin->getParsedResults(\'gajdaw.pl\');

API przygotowane przez portal Yahoo! stanowi
dobry przykład tego typu rozwiązań. Mając doświadczenie
w jego opanowywaniu, można potem
z powodzeniem zająć się wdrażaniem u siebie
innych API. A tych w sieci brakuje, tak samo jak
stron, które pomysłowemu wykorzystaniu gotowych
API zawdzięczają swoją dużą popularność.