Utilizzare l'API del New York Times per ottenere Metadati

Introduzione

La settimana scorsa abbiamo pubblicato un'introduzione dal titolo scraping web pages to collect metadata, menzionando il fatto che non è possibile analizzare i dati del sito del New York Times. Il paywall del Times blocca i vostri tentativi di ottenere banali metadati. C'è comunque un modo per aggirare il problema attraverso l'API del New York Times.

Recentemente abbiamo iniziato a sviluppare un sito in comunità che si appoggia alla piattaforma Yii, di cui abbiamo scritto a riguardo in Programming With Yii2: Building Community with Comments, Sharing and Voting (Envato Tuts+). Volevamo rendere facile aggiungere collegamenti relativi ai contenuti del sito. Mentre è facile per le persone incollare URLs all'interno di forms, richiede tempo fornire titolo e informazioni sulla fonte.

Quindi nel tutorial di oggi espanderemo il codice scritto recentemente per fare leva sull'API del New York Times al fine di ottenere titoli quando vengono aggiunti collegamenti del Times.

Ricordate, parteciperemo ai commenti sottostanti, quindi diteci cosa ne pensate! Potete anche raggiungerci tramite Twitter @lookahead_io.

Introduzione

Registratevi per una chiave API

In primo luogo registriamoci per richiedere una chiave API:

Dopo che avrete compilato il form riceverete la vostra chiave tramite email:

Esplorare l'API del New York Times

Il Times fornisce APIs nelle seguenti categorie:

• Archivio
• Ricerca articoli
• Libri
• Community
• Geografia
• Popolari
• Recensioni Film
• Semantica
• Times Newswire
• TimesTags
• Top Stories

È parecchio. Inoltre dalla pagina della Gallery potete cliccare su qualsiasi topic per vedere la documentazione della categoria individuale dell'API.

Il Times utilizza LucyBot per potenziare la documentazione delle API, ed è disponibile un'utile FAQ: 

Vi mostrano anche come ottenere velocemente i limiti di utilizzo dell'API (ne avrete bisogno per inserire la chiave):

 curl --head 
   https://api.nytimes.com/svc/books/v3/lists/overview.json?api-key=<your-api-key>
    2>/dev/null | grep -i "X-RateLimit"
    X-RateLimit-Limit-day: 1000
    X-RateLimit-Limit-second: 5
    X-RateLimit-Remaining-day: 180
    X-RateLimit-Remaining-second: 5

È stata inizialmente una lotta dare senso alla documentazione - si tratta di una specifica basata sul parametro, non una guida di programmazione. Comunque, abbiamo pubblicato alcune domande (issues) sulla pagina GitHub dell'API del New York Times, e abbiamo ricevuto risposte immediate e utili.

Lavorare con la Ricerca Articoli

Per l'episodio di oggi, ci concentreremo sull'utilizzo della ricerca degli articoli nel NY Times. Fondamentalmente estenderemo il form Create Link dell'ultimo tutorial:

Quando l'utente cliccherà Lookup eseguiremo una richiesta ajax tramite Link::grab($url). Ecco il jQuery:

$(document).on("click", '[id=lookup]', function(event) {
  $.ajax({
     url: $('#url_prefix').val()+'/link/grab',
     data: {url:   $('#url').val()},
     success: function(data) {
       $('#title').val(data);
       return true;
     }
  });
});

Di seguito il metodo controller e model: 

// Controller call via AJAX Lookup request
public static function actionGrab($url) {
  Yii::$app->response->format = Response::FORMAT_JSON;
  return Link::grab($url);
}
...
// Link::grab() method
public static function grab($url) {
  //clean up url for hostname
  $source_url = parse_url($url);
  $source_url = $source_url['host'];  
  $source_url=str_ireplace('www.','',$source_url);
  $source_url = trim($source_url,' \\');
  // use the NYT API when hostname == nytimes.com 
  if ($source_url=='nytimes.com') {
   ...

Poi useremo la nostra chiave API per eseguire una richiesta di ricerca articoli:

    $nytKey=Yii::$app->params['nytapi'];    
    $curl_dest = 'http://api.nytimes.com
        /svc/search/v2/articlesearch.json?fl=headline&fq=web_url:%22'.
        $url.'%22&api-key='.$nytKey;
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_URL,$curl_dest);
    $result = json_decode(curl_exec($curl));
    $title = $result->response->docs[0]->headline->main;
  } else {
    // not NYT, use the standard metatag scraper from last episode
         ...
    }
  }
  return $title;
}

E funziona abbastanza facilmente — ecco il titolo restituito (a proposito, climate change is killing Polar Bears and we should care):

Se volete maggiori dettagli dalla richiesta API aggiungete semplicemente argomenti ulteriori alla richiesta ?fl=headline come keywords e lead_paragraph:

Yii::$app->response->format = Response::FORMAT_JSON;
$nytKey=Yii::$app->params['nytapi'];
$curl_dest = 'http://api.nytimes.com/svc/search/v2/articlesearch.json?'.
  'fl=headline,keywords,lead_paragraph&fq=web_url:%22'.$url.'%22&api-key='.$nytKey;
$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_URL,$curl_dest);
$result = json_decode(curl_exec($curl));
var_dump($result);

Ecco il risultato:

Probabilmente scriveremo una libreria PHP per ottenere un miglior parsing dall'API NYT nei prossimi episodi, ma il codice sottostante riporta le keywords e il paragrafo principale:

Yii::$app->response->format = Response::FORMAT_JSON;
$nytKey=Yii::$app->params['nytapi'];
$curl_dest = 'http://api.nytimes.com/svc/search/v2/articlesearch.json?'.
  'fl=headline,keywords,lead_paragraph&fq=web_url:%22'.$url.'%22&api-key='.$nytKey;
$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_URL,$curl_dest);
$result = json_decode(curl_exec($curl));
echo $result->response->docs[0]->headline->main.'<br />'.'<br />';
echo $result->response->docs[0]->lead_paragraph.'<br />'.'<br />';
foreach ($result->response->docs[0]->keywords as $k) {
  echo $k->value.'<br/>';
}

Ecco cosa mostra per quest'articolo:

Polar Bears’ Path to Decline Runs Through Alaskan Village

The bears that come here are climate refugees, on land because
the sea ice they rely on for hunting seals is receding.

Polar Bears
Greenhouse Gas Emissions
Alaska
Global Warming
Endangered and Extinct Species
International Union for Conservation of Nature
National Snow and Ice Data Center
Polar Bears International
United States Geological Survey

Si spera che tutto ciò inizi ad espandere la vostra immaginazione riguardo l'utilizzo di queste APIs. È piuttosto eccitante cosa può risultare ora possibile.

Per finire

L'API del New York Times è veramente utile, e sono lieto di vederla offerta alla community di sviluppatori. È stato inoltre piacevole ottenere supporto così rapido attraverso GitHub - non ce lo aspettavamo. Tenete a mente che l'utilizzo è consentito per progetti non commerciali. Se avete qualche idea per fare soldi inviate loro una nota per vedere se hanno intenzione di lavorare con voi. Gli editori sono sempre desiderosi di nuove fonti di reddito.

Speriamo abbiate trovato questi episodi utili e che li abbiate utilizzati nei vostri progetti. Se volete vedere l'episodio di oggi in azione, potete provare sul nostro sito Active Together. 

Per favore condividete qualsiasi riflessione e feedback nei commenti. Potete anche raggiungerci direttamente tramite Twitter @lookahead_io. Assicuratevi inoltre di controllare la nostra pagina da istruttore e le altre serie, Building Your Startup With PHP e Programming With Yii2.

Link correlati

• The New York Times API Gallery
• The New York Times Public API Specs on GitHub
• How to Scrape Web Pages for Metadata (Envato Tuts+)
• How to Scrape Web Pages With Node.js and jQuery (Envato Tuts+)
• Building Your First Web Scraper in Ruby (Envato Tuts+)