Использование XML API на QRZ.RU

QRZ.RU предоставляет XML API для получения доступа к Callbook. Этот сервис позволяет получать информацию из базы данных позывных, и используется в программных аппаратных журналах

Внимание!

Сервис предназначен только для персонального использования в аппаратных журналах. Любые другие случаи использования приведут к блокировке аккаунта.

Поддерживаемые аппаратные журналы

Список известных аппаратных журналов, которые поддерживают XML API:

• AALog
• LogHX
• Logger32
• UR5EQF Log - пошаговое описание настройки доступа
• РадиоКРОТ (описание настройки доступа находится в файле документации, предоставляемым вместе с дистрибутивом)
• EWLOG
• Онлайн-журнал RV6AMZ
• Система CheckLog

Если вы обладаете информацией, о том что QRZ.RU API стала поддерживать программа, которой нет в этом списке - пожалуйста дайте нам знать через форму обратной связи, мы добавим ссылку на эту программу в список

Порядок получения доступа в XML API

Получение аккаунта для доступа в XML API осуществляется для зарегистрированных пользователей, имеющих действующий пстоянный позывной радиолюбителя или наблюдателя. Обратите внимание что:

1. XML API аккаунт предоставляется только на постоянные позывные радиолюбителя и наблюдателя. Временные позывные, радиомаяки и репитеры - XML API не предоставляется.
2. Для регистрации XML API аккаунта вам необходимо иметь соответствующую запись своего позывного в QRZ.RU Callbook.

Для получения доступа вам необходимо авторизоваться в личном кабинете, и перейти на страницу "Личные данные". Внизу страницы в разделе XML API перейдите по ссылке "Создать аккаунт".

В открывшейся форме укажите:

• Свой радиолюбительский позывной
• Название программы, в которой будете использовать XML API доступ

После отправки формы на сервер через некоторое время вы получите информацию по доступу (логин/пароль), либо мотивированный отказ в активации доступа.

Описание протокола работы XML API для разработчиков

Внимание. Ниже приведено описание работы API, содержащее технические подробности для специалистов. Если вы не являетесь разработчиком - пропустите этот раздел.

XML API расположено по адресу http://api.qrz.ru/

Все ответы сервера осуществляются в кодировке UTF-8

Порядок работы:

1. Авторизуемся в API, получаем код сессии

Код:

https://api.qrz.ru/login?u=<username>&p=<password>&agent=<agent>

где

u - имя пользователя (логин) XML API (обязательный параметр)
p - пароль пользователя XML API (обязательный параметр)
agent - программное обеспечение (название, версия) которое запрашивает доступ.
Если параметр не задан, используется переменная HTTP_USER_AGENT из служебных заголовков сервера

Для сохранения конфиденциальности логина/пароля рекомендуется параметры передавать POST запросом

Ответ сервера в случае корректной авторизации

Код:

<?xml version="1.0"?>
<QRZDatabase version="1.0" xmlns="http://api.qrz.ru/namespace">
<Session>
    <session_id>eda28b5e22790226247551ad32c2a71a</session_id>
    <GMTime>Sun, 27 Oct 2013 15:46:58 +0000</GMTime>
</Session>
</QRZDatabase>

либо в случае отказа в авторизации

Код:

<?xml version="1.0"?>
<QRZDatabase version="1.0" xmlns="http://api.qrz.ru/namespace">
<session>
    <errorcode>403</errorcode>
    <error>Wrong user name or password</error>
</session>
</QRZDatabase>

Время жизни предоставленного ключа сессии - 1 час. По истечении этого времени вы получите ошибку

Код:

<?xml version="1.0"?>
<QRZDatabase version="1.0" xmlns="http://api.qrz.ru/namespace">
<session>
    <errorcode>403</errorcode>
    <error>Session does not exist or expired</error>
</session>
</QRZDatabase>

что означает - вам следует снова авторизоваться

2. Осуществляем запросы в рамках предоставленной сессии

Общий синтаксис запроса:

Код:

https://api.qrz.ru/callsign?id=<session_id>&callsign=<callsign>

где
id -идентификатор сессии выданный после авторизации (точное соответствие)
callsign - интересующий вас позывной (любой регистр)

На примере позывного UA9OTY и выданного выше номера сессии:

Код:

https://api.qrz.ru/callsign?id=eda28b5e22790226247551ad32c2a71a&callsign=ua9oty

Ответ сервера будет таким:

Код:

<?xml version="1.0"?>
<QRZDatabase version="1.0" xmlns="http://api.qrz.ru/namespace">
<Callsign>
    <call>UA9OTY</call>
    <type>0</type>
    <othercall>UA0SRX</othercall>
    <surname>Ильюхин</surname>
    <name>Сергей</name>
    <name2>Юрьевич</name2>
    <esurname>Ilyukhin</esurname>
    <ename>Sergey</ename>
    <ename2>Yurievich</ename2>
    <birthday>05.01.1975</birthday>
    <dayofdeath></dayofdeath>
    <zip>630089</zip>
    <city>Новосибирск-89,</city>
    <street>а/я 467</street>
    <country>Россия</country>
    <url>http://www.qsl.net/ua9oty</url>
    <icq>7426815</icq>
    <skype>ua9oty</skype>
    <created>02.07.2005 17:25:55</created>
    <lastedit>25.11.2009 23:25:34</lastedit>
    <lookup>16397</lookup>
</Callsign>
<Files>
</Files>
<Session>
    <session_id>eda28b5e22790226247551ad32c2a71a</session_id>
    <GMTime>Sun, 27 Oct 2013 15:55:27 +0000</GMTime>
</Session>
</QRZDatabase>

Где блок <Callsign> содержит информацию о позывном, <Files> - список всех вложенных в колбук файлах этого позывного (сейчас это одно фото, в следующем году сделаем групповое хранение нескольких файлов), <Session> - справочная информация (id сессии и GMT время на сервере)

если позывной не найден в базе данных, сервер сообщит:

Код:

<?xml version="1.0"?>
<QRZDatabase version="1.0" xmlns="http://api.qrz.ru/namespace">
<session>
    <errorcode>404</errorcode>
    <error>Callsign not found</error>
</session>
</QRZDatabase>

Ограничения при работе:

В связи с ограниченностью ресурсов сервера применяются следующие ограничения:

• На один IP адрес - не более одного подключения. Параллельные подключения запрещены.
• При первоначальной авторизации без ограничения скорости - 3 запроса (получения ID сессии и два запроса на поиск). Далее - не более одного запроса в 3 секунды.

Разработчикам - для получение XML доступа в базу данных обращайтесь через форму обратной связи

Для пакетных запросов на обработку позывных сотнями/тысячами записей - обращайтесь через форму обратной связи