# Aviasales Data API (Travelpayouts): Подобрать, куда дёшево улететь из города

Сценарий из mcp-everything. Актуально на 2026-10-24.

Подборка «Куда полететь из Екатеринбурга» — направления с самыми низкими ценами.

1. Запроси билеты только с городом вылета: GET /aviasales/v3/prices_for_dates с origin, departure_at, unique = true (по одному билету на направление) и sorting = price.
2. Для акцентов добавь аномально дешёвые предложения: GET /aviasales/v3/get_special_offers с origin и currency.
3. Если направление задано, а даты гибкие, подскажи соседние аэропорты: GET /v2/prices/nearest-places-matrix с origin, destination, flexibility (0–7 дней) и distance (число вариантов).
4. Названия городов по IATA-кодам храни у себя: API возвращает только коды.

```bash
curl -G "https://api.travelpayouts.com/aviasales/v3/prices_for_dates" \
  -H "X-Access-Token: $TP_TOKEN" --compressed \
  -d origin=SVX -d departure_at=2026-12 -d unique=true -d sorting=price -d limit=20 -d currency=rub

curl -G "https://api.travelpayouts.com/aviasales/v3/get_special_offers" \
  -H "X-Access-Token: $TP_TOKEN" --compressed -d origin=SVX -d currency=rub
```

## Базовые URL

- Боевой: `https://api.travelpayouts.com`

## Авторизация

Тип: API-ключ

API-токен из профиля Travelpayouts (раздел «API-токен») передаётся в заголовке `X-Access-Token` или в параметре `token`.

```
https://api.travelpayouts.com/aviasales/v3/prices_for_dates?origin=MAD&destination=BCN&departure_at=2023-07&return_at=2023-08&unique=false&sorting=price&direct=false&cy=usd&limit=30&page=1&one_way=true&token=PutYourTokenHere
```

## Методы сценария

### GET /aviasales/v3/prices_for_dates — Билеты на конкретные даты

Самые дешёвые билеты на даты, найденные за последние 48 часов. Заменяет `/v1/city-directions`, `/v1/prices/cheap`, `/v1/prices/direct`, `/v2/prices/latest`.

В ответе для каждого билета: `origin`, `destination`, `price`, `airline`, `flight_number`, `departure_at`, `return_at`, `transfers`, `duration`, `link`. Ссылку `link` добавляют к `https://www.aviasales.com/`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | query | string | да | API-токен (или заголовок X-Access-Token) |
| `origin` | query | string | нет | IATA-код города или аэропорта вылета |
| `destination` | query | string | нет | IATA-код назначения; обязателен, если нет origin |
| `departure_at` | query | string | нет | Дата вылета YYYY-MM или YYYY-MM-DD |
| `return_at` | query | string | нет | Дата возвращения; для билетов в одну сторону не указывать |
| `one_way` | query | boolean | нет | В одну сторону, по умолчанию true |
| `direct` | query | boolean | нет | Только прямые, по умолчанию false |
| `currency` | query | string | нет | Валюта, по умолчанию RUB |
| `market` | query | string | нет | Рынок данных, по умолчанию ru |
| `limit` | query | integer | нет | Записей на странице, по умолчанию 30, максимум 1000 |
| `page` | query | integer | нет | Номер страницы |
| `sorting` | query | string | нет | price (по умолчанию) или route (популярность) |
| `unique` | query | boolean | нет | Только уникальные направления, если указан лишь origin |

### GET /v2/prices/nearest-places-matrix — Цены по альтернативным направлениям

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | query | string | да | API-токен |
| `origin` | query | string | нет | IATA-код вылета |
| `destination` | query | string | нет | IATA-код назначения |
| `limit` | query | integer | нет | Число вариантов, 1–20 |
| `depart_date` | query | string | нет | Месяц вылета yyyy-mm |
| `return_date` | query | string | нет | Месяц возвращения yyyy-mm |
| `flexibility` | query | integer | нет | Расширение диапазона дат, 0–7 дней |
| `distance` | query | integer | нет | Число вариантов, 1–20 |
| `show_to_affiliates` | query | boolean | нет | Только цены по партнёрскому маркеру |
| `currency` | query | string | нет | Валюта |

### GET /aviasales/v3/get_special_offers — Спецпредложения

Аномально низкие цены на выбранные направления. Если `origin` не указан, определяется по IP.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | query | string | да | API-токен |
| `origin` | query | string | нет | IATA-код вылета |
| `destination` | query | string | нет | IATA-код назначения |
| `airline` | query | string | нет | IATA-код авиакомпании |
| `locale` | query | string | нет | Язык |
| `currency` | query | string | нет | Валюта |
| `market` | query | string | нет | Рынок данных |

## Нюансы

- Ответ: `success` (`true`/`false`), `data` (при ошибке — `{}`), `error` (`null` при успехе).
- Даты — `YYYY-MM` или `YYYY-MM-DD`; время в ответах — UTC, ISO 8601. Цены по умолчанию — в рублях.
- Не используйте устаревшие цены: ориентир срока — поле `expires_at`.
- Рынок (`market`) по умолчанию определяется по месту вылета, иначе — `ru`; данные разных рынков не пересекаются.
- Рекомендуется получать ответы в gzip: заголовок `Accept-Encoding: gzip, deflate`.
- Логотипы авиакомпаний: `http://pics.avs.io/{width}/{height}/{iata}.png`.
- Устаревшие методы `/v1/prices/cheap`, `/v1/prices/direct`, `/v1/prices/calendar`, `/v1/city-directions`, `/v1/airline-directions` заменяются `prices_for_dates` и `grouped_prices`.

## Другие сценарии

- [Показать дешёвые билеты по направлению](https://mcp-everything.ru/integrations/travelpayouts-aviasales/scenarios/pokazat-deshevye-bilety-po-napravleniyu.md)
- [Построить календарь цен](https://mcp-everything.ru/integrations/travelpayouts-aviasales/scenarios/postroit-kalendar-tsen.md)
- [Найти билеты в рамках бюджета](https://mcp-everything.ru/integrations/travelpayouts-aviasales/scenarios/nayti-bilety-v-ramkah-byudzheta.md)

---

Если этого недостаточно — официальная документация: https://support.travelpayouts.com/hc/en-us/articles/203956163
Вся интеграция одним документом: https://mcp-everything.ru/integrations/travelpayouts-aviasales.md