Twitter API: курс молодого бойца

По почте я постоянно получаю письма с просьбой посмотреть тот или иной код (хотя, вроде бы, я уже давно не позиционирую себя как хорошего программиста) и указать на имеющиеся в нем ошибки. Большую часть авторов этих писем волнуют проблемы, связанные с работой Twitter API в общем и тем или иным функционалом рейтинга Twirate (который, напоминаю, уже мне не принадлежит) в частности.

В этой статье я расскажу об основах работы с Twitter API, приведу готовые куски кода, а также постараюсь ответить на ваши вопросы, если таковые будут.

Итак, давайте сначала определимся вот с чем. Зачем он, собственно, нужен этот Twitter API и какую пользу он может принести вебмастеру? Среднестатическому клепателю псевдосайтов он, скорее всего, будет бесполезен, но вебмастеру-профессионалу API этой популярной социальной сети может принести ощутимую пользу и как база для создания новых сервисов/стартапов, и как средство разработки дополнительных инструментов продвижения для вполне конкретного сайта.

Кстати, допущу небольшой инсайд — в скором времени мы с вами займемся написанием учебного кросспостера в социальные сети, где нам и пригодятся знания, полученные из этого поста. Рекомендую подписаться на блог, чтобы ничего не пропустить. Кнопка подписки находиться слева.

Но ближе к делу. Для понимания и применения знаний, изложенных в этой статье, нам понадобиться следующее:

• Знание PHP на твердом среднем уровне;
• Знание и понимание социальной сети Twitter;
• Наличие свободного времени для экспериментов;
• Традиционно — прямые руки.

Начнем с основ.

Принцип работы

В общем и целом, всю работу с Twitter API можно свести к следующей схеме:

1. Отправляем GET-запрос с параметрам (если есть) по адресу нужной нам функции;
2. Получаем XML или jSON данные (в зависимости от выбранного формата);
3. Если есть необходимость — парсим эти данные.

Например, для того, чтобы получить всю информацию о нужном нам аккаунте, достаточно отправить GET-запрос по адресу

http://twitter.com/users/show/имя_аккаунта

В ответ, Twitter выдаст нам полную информацию об этом аккаунте, включая текст последнего твита.

Эта схема подходит под абсолютное большинство функций Твиттера. Различие будет лишь в передаваемых параметрах и структуре получаемых данных. Сложно? Хорошо, давайте подробно разберем простейшее Twitter-приложение, которое будет запрашивать и выводить основные параметры выбранного аккаунта.

Пример приложения

Для начала, традиционно, выполним подготовку интерфейса — в нашем случае, это будет простенькая форма:

<form action='twiapi.php' method='POST'><input type='edit' name='account' value='account'])?$_POST['account']:''?>' /> 

<input type='submit' name='Submit' value='Получить данные' />form>

Далее, смотрим в список функций на портале dev.twitter.com и выбираем нужную нам функцию. Поскольку мы решили создавать приложение, которое будет выводить основные параметры выбранного аккаунта, то остановим свой выбор на функции users/show. В качестве параметра, эта функция принимает имя аккаунта, для которого необходимо получить характеристики (есть и некоторые другие параметры, но в учебных целях, мы остановимся только на этом).

Вот пример готового модуля реализующего запрос числа фолловеров, фолловингов и последнего твита выбранного аккаунта. Обратите внимание, для работы этого скрипта вам нужно в переменных $username и $password указать имя и пароль от какого-либо аккаунта в Твиттере, который будет использоваться для формирования запросов.

$account = ИМЯ_АККАУНТА;    $username = ИМЯ_АККАУНТА_ОТ_КОТОРОГО_БУДЕМ_ПОСЫЛАТЬ_ЗАПРОС;    $password = ПАРОЛЬ_АККАУНТА_ОТ_КОТОРОГО_БУДЕМ_ПОСЫЛАТЬ_ЗАПРОС;        $context = stream_context_create(array(        'http' => array(            'header' => "Authorization: Basic ".base64_encode("$username:$password")        )    )); // выполняем авторизацию            $api_page = 'http://twitter.com/users/show/'.$account; // адрес страницы-функции для запроса    $xml = @file_get_contents ($api_page, false, $context); // выполняем запрос        $profile = new SimpleXMLElement ($xml); // разбираем полученный XML-поток     echo 'Фолловеров: '.$profile->followers_count.'
'; // выводим число фолловеров    echo 'Фолловингов: '.$profile->friends_count.'
'; // выводим число фолловингов    echo 'Последний твит: '.$profile->status->text.'
'; // выводим последний твит?>

Просто, правда? Давайте встроим этот алгоритм в наш код с формой и посмотрим на результат.

<form action='twiapi.php' method='POST'><input type='edit' name='account' value='=isset($_POST['account'])?$_POST['account']:''?>' /> 

<input type='submit' name='Submit' value='Получить данные' />form> if (isset($_POST) and !empty($_POST['account'])){    $account = $_POST['account'];    $username = 'ВВЕДИТЕ СЮДА ИМЯ ВАШЕГО АККАУНТА В ТВИТТЕР';    $password = 'ВВЕДИТЕ СЮДА ПАРОЛЬ ВАШЕГО АККАУНТА В ТВИТТЕР';        $context = stream_context_create(array(        'http' => array(            'header' => "Authorization: Basic ".base64_encode("$username:$password")        )    ));        $api_page = 'http://twitter.com/users/show/'.$account;    $xml = @file_get_contents ($api_page, false, $context);     $profile = new SimpleXMLElement ($xml);            echo 'Фолловеров: '.$profile->followers_count.'
';    echo 'Фолловингов: '.$profile->friends_count.'
';    echo 'Последний твит: '.$profile->status->text.'
';}?>

Работает этот код примерно так.

В принципе, этот скрипт готов к употреблению, но я предлагаю немного его доработать, чтобы он корректно обрабатывал возможные ошибки со стороны Твиттера, которые встречаются у него с незавидной частотой (например, классическая ошибка с превышением нагрузки на сервер Twitter, вызывающая картинку, где птички пытаются поднять слона). Для этого добавим пару обработчиков, которые я не буду приводить отдельно.

Вот итоговый код скрипта, корректно обрабатывающий ситуации, когда указанного аккаунта не существует или он заблокирован, а также любые другие ошибки со стороны Twitter.

<form action='twiapi.php' method='POST'><input type='edit' name='account' value='=isset($_POST['account'])?$_POST['account']:''?>' /> 

<input type='submit' name='Submit' value='Получить данные' />form> if (isset($_POST) and !empty($_POST['account'])){    $account = $_POST['account'];    $username = '';    $password = '';        $context = stream_context_create(array(        'http' => array(            'header' => "Authorization: Basic ".base64_encode("$username:$password")        )    ));        libxml_use_internal_errors(true);        $api_page = 'http://twitter.com/users/show/'.$account;    $xml = @file_get_contents ($api_page, false, $context);        if ($xml == false)    {        if ($hdrs = @get_headers('http://twitter.com/users/show/'.$account))        {            if (substr(strchr($hdrs[0], ' '), 1, 3)==='404')            {                echo 'Данный аккаунт заблокирован или не существует';                exit(1);            }        }        else        {            echo 'Ошибка сервера';            exit(1);        }    }        try    {        $profile = new SimpleXMLElement ($xml);    }     catch (Exception $ex)    {        echo 'Ошибка сервера';        exit(1);    }    echo 'Фолловеров: '.$profile->followers_count.'
';    echo 'Фолловингов: '.$profile->friends_count.'
';    echo 'Последний твит: '.$profile->status->text.'
';}?>

Скрипт завершен и готов к употреблению! Теперь давайте разберем несколько вопросов, которые волновали авторов писем в моем почтовом ящике и аське.

Вопросы и ответы по Twitter API

Как получить число листов (listed), в которые был добавлен конкретный аккаунт?

Увы, готовой функции для этого, программисты Twitter не предусмотрели, хотя их неоднократно об этом просили. Поэтому я предлагаю свое решение для получения этого параметра. Вот готовая функция, принимающая в качестве единственного параметра, имя аккаунта для, которого необходимо подсчитать число listed:

function get_twitter_listed($account){        $username = 'ВВЕДЕТЕ СЮДА ИМЯ ВАШЕГО АККАУНТА В ТВИТТЕР';        $password = 'ВВЕДЕТЕ СЮДА ПАРОЛЬ ВАШЕГО АККАУНТА В ТВИТТЕР';                $context = stream_context_create(array(            'http' => array(                'header' => "Authorization: Basic ".base64_encode("$username:$password")            )        ));                $api_page = "http://api.twitter.com/1/$account/lists/memberships.xml";        $xml = @file_get_contents ($api_page, false, $context);                            $memberships = new SimpleXMLElement ($xml);                $listed_count = count($memberships->lists->list);         while(count($memberships->lists->list))        {            $api_page = "http://api.twitter.com/1/$account/lists/memberships.xml?cursor=".$memberships->next_cursor;            $xml = @file_get_contents ($api_page, false, $context);                        $listed_count += count($memberships->lists->list);         }                return $listed_count;}?>

Принцип ее работы прост: она "пробегается" по всем листам, в которые был добавлен аккаунт и подсчитывает их суммарное количество. Решение очень ресурсоемкое, но другого пока нет. Кстати в Twirate работает именно оно.

Как увеличить лимит запросов, налагаемый на аккаунт?

Каждый стандартный аккаунт может сделать не более 150 запросов к Twitter API в час. Но в ряде случаев этой квоты не хватает и хочется большего. Для этого разработчики Твиттера ввели процедуру под названием whitelistening (я называю ее "отбеливание" :). Выполняет она довольно просто: идем по этому адресу и заполянем следующие формы:

• Do you want to whitelist an IP(s) in addition to your account?. Если вам не нужна привязка вашего "отбеленного" аккаунта к IP — оставляем это поле пустым;
• Describe your project in detail. Здесь описываем свой проект для которого нам нужен "отбеленный" аккаунт и четко обосновываем для чего нам необходимы дополнительные мощности. Отнеситесь к этому пункту серьезно, кому попало они ресурсы не выделяют;
• Please provide contact information. На всякий случай указываем здесь свой email;
• Whitelist your user account?. Если в данный момент вы как раз выполнили вход тем аккаунтом, который нужно "отбелить" — ставим здесь галочку;

Вот и все — отправляем форму и ждем рассмотрения заявки в течении двух недель (иногда больше, иногда меньше). Если все пройдет удачно, лимит вашего аккаунта станет 20000 запросов в час.

Как посмотреть оставшийся лимит запросов у аккаунта?

Введите в браузер следующий адрес

http://api.twitter.com/1/account/rate_limit_status.xml?account=ИМЯ_АККАУНТА

Вам будет выдан XML-поток. Оставшееся число запросов будет указано в поле "remaining-hits". Кстати, этим методом можно отслеживать, "отбелили" ли ваш аккаунт после отправки вами заявки из предыдущего вопроса или еще нет.

Заключение

Разработка приложений под Twitter — это целая область знаний, которая станет (и уже становится!) прибыльным направлением ведения дел. Надеюсь, этот небольшой ликбез позволит вам окунуться в этот увлекательный мир, где взаимодействует программный код и большой дата-центр синей птички.

Если у вас есть какие-либо вопросы — добро пожаловать в комментарии. Кстати, нелишним будет заглянуть и в недавно сформированный центр разработчиков для Твиттер.