API

Модель данных
Соглашения:
  1. У всех сущностей имеется уникальный идентификатор, который никогда не будет изменен.
  2. У некоторых сущностей имеется атрибут "name" (наименование), который всегда дублируется на нескольких языках, при этом в конце названия поля добавляется приставка с соответствующей локалью. Пример: значение атрибута "name" на англ. языке будет содержать поле "name_en", а на русском "name_ru". Со временем список локализованных наименований будет расширяться и, как следствие, в модель данных будут добавляться новые поля "name_%locale%", например "name_fr" для французского языка

Схема связей между сущностными:
UrlDomain (URL-домен)
Описание:
Содержит данные по url-домену 1-ого и 2-ого уровней для локализованных версий сайта KiwiTaxi

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. locale (string) - локаль (en, ru, fr и т.д.)
  3. value (string) - домен (kiwitaxi.com, kiwitaxi.ru и т.д.)
Сущность "Currency"(Валюта)
Описание: ~

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. code (string) - трехсимвольный уникальный код валюты
  3. iso (integer) - числовой уникальный ISO-код валюты
Сущность "Country" (Страна)
Описание: ~

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. iata (string) - уникальный двухсимвольный код IATA (ISO)
  3. published (boolean) - доступность заказа трансферов из страны (см. комментарий ниже)
  4. name_en (string) - английская версия наименования
  5. name_ru (string) - русская версия наименования
  6. currency_id (integer) - уникальный идентификатор валюты используемой в стране
  7. time_zone (string) - смещение локального времени страны в часах относительно UTC без учета перевода на зимнее и летнее время, пример значений: "+2", "+10", "-3" и т.п.

Комментарий:
Важное уточнение по поводу атрибута "published". Если значение атрибута равно "False", то заказ трансферов в этой стране невозможен, но возможен заказ трансфера из другой доступной страны в эту. Такая ситуация может возникнуть, например, в Евросоюзе в случае двух соседних стран.

Пример:
Предположим, что у Бельгии "published == false", а у Франции "published == true", тогда трансферы "Брюссель-Шарлеруа Аэропорт => Париж" недоступны для бронирования, а обратные "Париж => Брюссель-Шарлеруа Аэропорт" доступны.
Сущность "Region" (Регион)
Описание:
Как правило службы такси не могут территориально работать по всей стране, поэтому страна поделена на регионы в которых они способны принять и выполнить заказ. Регион может как совпадать с реальным географическим регионом в стране, так и быть "виртуальным", т.е. быть какой-либо произвольной именованной областью внутри страны.

Атрибуты:
  1. id (integer) - уникальный идентификатор региона
  2. country_id (integer) - уникальный идентификатор страны к которой относится регион
  3. name_en (string) - английская версия наименования
  4. name_ru (string) - русская версия наименования
Сущность PlaceType
(Тип маршрутной точки)
Описание:
Тип маршрутной точки (географического места), например: Город, Аэропорт и т.п.

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. name_en (string) - английская версия наименования
  3. name_ru (string) - русская версия наименования
Сущность "Place"
(Маршрутная точка)
Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. country_id (integer) - уникальный идентификатор страны в которой находится маршрутная точка
  3. region_id (integer) - уникальный идентификатор региона в котором находится маршрутная точка
  4. type_id (integer) - уникальный идентификатор типа маршрутной точки
  5. name_en (string) - английская версия наименования
  6. name_ru (string) - русская версия наименования
  7. name_de (string) - немецкая версия наименования
  8. name_fr (string) - французская версия наименования
  9. name_es (string) - испанская версия наименования
  10. iata (string) - уникальный код ИАТА
  11. place_polygon (polygon) - геозона в виде набора геоточек (lon, lat), в БД хранится как тип "geometry" MySQL
Сущность "Route" (Маршрут)
Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. country_id (integer) - уникальный идентификатор страны в которой находится/начинается маршрут
  3. place_from_id (integer) - уникальный идентификатор начальной точки (места) маршрута
  4. place_to_id (integer) - уникальный идентификатор конечной точки (места) маршрута
  5. distance (integer) - расстояние в километрах между начальной и конечной маршрутными точками
  6. timeinway (integer) - приблизительное время поездки в минутах по маршруту
  7. weight (float) - сорт. вес (процент продаж трансферов по маршруту за текущий сезон: зима, весна и т.д.)
  8. url (string) - относительный URL на список трансферов по маршруту
Сущность "TransferType"
(Тип трансфера)
Описание: Содержит данные о классах машин (эконом, минивэн, минибас и пр.), которые доступны для заказа

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. name_en (string) - англиская версия наименования
  3. name_ru (string) - русская версия наименования
  4. pax (integer) - максимальное количество пассажиров (включая младенцев и детей)
  5. baggage (integer) - максимальное количество багажных мест
  6. description_en (string) - англ. версия описания
  7. description_ru (string) - рус. версия описание
  8. car_examples_en (string) - примеры машин на англ.
  9. car_examples_ru (string) - примеры машин на рус.
  10. photo (string) - абсолютный (полный ) URL на стилизованную картинку класса машины
  11. sortno (integer) - сортировочный вес
Сущность "Transfer" (Трансфер)
Описание: ~

Атрибуты:
  1. id (integer) - уникальный идентификатор
  2. route_id (integer) - уникальный идентификатор маршрута
  3. type_id (integer) - уникальный идентификатор типа трансфера
  4. price_rub (flot) - стоимость в рублях
  5. price_eur (float) - стоимость в евро
  6. price_usd (float) - стоимость в долларах США
  7. url (string) - относительный URL на заказ трансфер
Методы
Соглашения:
  1. Данные возвращаются при помощи отправки HTTP-запросов на определенные URL. В случае успеха сервер вернет HTTP status "200" и данные в формате "CSV"
  2. Все запросы должны содержать параметр "security_token". На данный момент он у всех одинаковый "24e8a1c890fb0d16ecdce4926dc4b2d6", в дальнейшем каждому пользователю будет присвоен индивидуальный токен безопасности
  3. Все методы возвращают полный набор данных без возможности фильтрации
  4. Записи разделены символом переноса строки "\n"
  5. Поля и их значения разделены символом табуляции "\t"
  6. В качестве значения "NULL" используется комбинация символов слэш и N: "\N"
  7. Первая запись в данных всегда содержит наименования полей сущности
  8. ВАЖНО! Во все ссылки на KiwiTaxi нужно добавить параметр "pap=%ваш партнерский ИД%". Иначе вам не будет начисляться комиссия с продаж.
1. Получить список URL-доменов (сущностей типа "UrlDomain"):
https://kiwitaxi.com/services/data/csv/url_domains
Параметры: ~

2. Получить список валют (сущностей типа "Currency"):
https://kiwitaxi.com/services/data/csv/currencies
Параметры: ~

3. Получить список стран (сущностей типа "Country"):
https://kiwitaxi.com/services/data/csv/countries
Параметры: ~

4. Получить список регионов (сущностей типа "Region"):
https://kiwitaxi.com/services/data/csv/regions
Параметры: ~

5. Получить список типов маршрутных точек (сущностей типа "PlaceType"):
https://kiwitaxi.com/services/data/csv/place_types
Параметры: ~

6. Получить список маршрутных точек (сущностей типа "Place"):
https://kiwitaxi.com/services/data/csv/places
Параметры: ~

7. Получить список маршрутов (сущностей типа "Route"):
https://kiwitaxi.com/services/data/csv/routes
Параметры: ~

8. Получить список маршрутов в формате для White Label (сущностей типа "Route"):
kiwitaxi.ru/services/data/csv/routes?security_token=24e8a1c890fb0d16ecdce4926dc4b2d6&white_label=1

9. Получить список типов трансферов (сущностей типа "TransferType"):
https://kiwitaxi.com/services/data/csv/transfer_types
Параметры: ~

10. Получить список трансферов (сущностей типа "Transfer"):
https://kiwitaxi.com/services/data/csv/transfers
Параметры: payment_type (string) - тип оплаты: "none" - без предоплаты, "partial" - частичная предоплата, "full" - 100% предоплата. В зависимости от типа предоплаты может меняться стоимость трансфера. Значение по умолчанию: "partial".
Пример (для PHP)
Задача: Необходимо получить полный список доступных маршрутов для дальнейшей обработки

При помощи URL (http://php.net/manual/ru/book.curl.php) вызываем метод https://kiwitaxi.com/services/data/csv/routes?security_token=24e8a1c890fb0d16ecdce4926dc4b2d6

Результат (в виде данных в формате "CSV") записываем в переменную $data

Дальше необходимо распарсить полученные данные в массив:
/* --------------------------------------------------------------------------------------------- */
$data = explode("\n", $data);
foreach ($data as &$item)
{
$item = explode("\t", $item);
}
unset($item);
// Получаем названия полей
$fields = $data[0];
unset($data[0]);
/* --------------------------------------------------------------------------------------------- */
В результате получим два массива:
  • $fields - со списком полей
  • $data - со списком значений