yandex-api/README.md

# Yandex API — локальные прокси-сервисы
API-ключ для работы в AI Studio
AQVN0kCCdlt598SE87sP52uZYaG2tNP0OajDoC7B

Идентификатор API-ключа
ajei8217cmrpuv289str

Два сервиса для работы с Яндекс.Директ API v5 и Яндекс.Вордстат (Yandex Cloud Search API v2), запущенные на `192.168.1.152` (nik).

## Сервисы

| Сервис | Порт | Назначение |
|--------|------|-----------|
| **Yandex Direct API** | 8456 | Управление кампаниями, группами, объявлениями, ключевыми словами |
| **Wordstat API** | 8457 | Сбор частотности, топ-запросы, динамика, география |

## Быстрый старт

### Подключение с другого компьютера в сети

С других машин локальной сети (192.168.1.x) сервисы доступны напрямую по HTTP:

```bash
# Проверка доступности
curl http://192.168.1.152:8456/
curl http://192.168.1.152:8457/health

# Простой запрос — без ключей (статус)
curl http://192.168.1.152:8456/
curl http://192.168.1.152:8457/health
```

> **Примечание:** для запросов к реальному API (не /health) сервисы используют токены, захардкоженные в `config.py` на сервере. Ключи не нужно передавать в запросах.

### Создание кампаний (Direct API)

```bash
# Получить статус сервера
curl http://192.168.1.152:8456/

# Список кампаний
curl http://192.168.1.152:8456/campaigns

# Создать кампанию
curl -X POST http://192.168.1.152:8456/campaigns \
  -H "Content-Type: application/json" \
  -d '{"name":"Моя кампания","daily_budget_rub":500,"strategy":"HIGHEST_POSITION"}'

# Создать группу объявлений
curl -X POST http://192.168.1.152:8456/adgroups \
  -H "Content-Type: application/json" \
  -d '{"name":"Группа 1","campaign_id":709606618,"region_ids":[225]}'

# Создать объявление
curl -X POST http://192.168.1.152:8456/ads \
  -H "Content-Type: application/json" \
  -d '{"adgroup_id":5747798281,"title":"Заголовок до 56 символов","text":"Текст объявления","href":"https://example.com"}'

# Добавить ключевые фразы
curl -X POST http://192.168.1.152:8456/keywords \
  -H "Content-Type: application/json" \
  -d '{"adgroup_id":5747798281,"keywords":[{"keyword":"купить слона","bid_rub":50}]}'

# Управляемые аккаунты (client_login)
curl http://192.168.1.152:8456/campaigns?client_login=casamebelads

# Регионы (с кириллицей — URL-кодировать!)
curl -s -G 'http://192.168.1.152:8456/dictionaries/regions' --data-urlencode 'search=Иглино'
```

### Сбор частотности (Wordstat API)

```bash
# Получить частотность запроса
curl -X POST http://192.168.1.152:8457/top \
  -H "Content-Type: application/json" \
  -d '{"phrase":"деревянные дома"}'

# Получить динамику по времени
curl -X POST http://192.168.1.152:8457/dynamics \
  -H "Content-Type: application/json" \
  -d '{"phrase":"купить деревянный дом"}'

# Распределение по регионам
curl -X POST http://192.168.1.152:8457/regions \
  -H "Content-Type: application/json" \
  -d '{"phrase":"деревянные дома"}'

# Справочник регионов (бесплатно, без квоты)
curl http://192.168.1.152:8457/regions/tree

# Статус API-ключа
curl http://192.168.1.152:8457/oauth/status

# Сохранённые ключевые слова
curl http://192.168.1.152:8457/keywords
```

## API-ключи и авторизация

Сервисы работают как локальный прокси — ключи хранятся на сервере `192.168.1.152`:

### Яндекс.Директ API (порт 8456)
- **OAuth-токен:** захардкожен в `config.py` на сервере
- **Режим:** production
- Для переключения на управляемые аккаунты — параметр `client_login`

### Wordstat API (порт 8457)
- **Yandex Cloud API Key:** хранится в `/home/neo/workspace/wordstat-api/.env`
- **Folder ID:** `b1g666nmgcdb1j6e551t`
- Получить ключ: https://aistudio.yandex.ru/

## Изменение API-ключей

Если нужно сменить ключи, подключись к `nik@192.168.1.152` по SSH и отредактируй конфиги:

```bash
# SSH на сервер
ssh nik@192.168.1.152

# Яндекс.Директ API — токен в config.py
nano /home/neo/workspace/yandex-direct-api/config.py

# Wordstat API — ключ в .env
nano /home/neo/workspace/wordstat-api/.env

# Перезапуск сервисов
systemctl --user restart yandex-direct-api
systemctl --user restart wordstat-api
```

## Удалённое подключение

С любого компьютера в сети `192.168.1.x`:

```python
import requests

# Яндекс.Директ
resp = requests.get("http://192.168.1.152:8456/")
print(resp.json())  # {"ok": true, "mode": "production", ...}

# Wordstat
resp = requests.get("http://192.168.1.152:8457/health")
print(resp.json())  # {"status": "ok", "api_key_set": true, ...}
```

## Порты и фаервол

Порты 8456 и 8457 должны быть доступны в локальной сети. Проверить:

```bash
# На сервере nik
ss -tlnp | grep -E '845[67]'

# Если порты не слушаются — проверить systemd сервисы
systemctl --user status yandex-direct-api wordstat-api
```

Если фаервол (UFW/firewalld) блокирует — разрешить:

```bash
sudo ufw allow from 192.168.1.0/24 to any port 8456
sudo ufw allow from 192.168.1.0/24 to any port 8457
```

## Ограничения и известное

- **Wordstat квота:** 100 запросов/час, 10/сек. Легко сжечь за минуту.
- **Wordstat status: Preview** — API может измениться.
- **Директ:** бюджет кампании минимум 300₽.
- **Директ API:** стратегия сетей `MAXIMUM_COVERAGE` не работает, использовать `SERVING_OFF`.
- **Директ API:** поле `DailyBudget: null` после создания — кампания может работать без лимита.
- **Директ API:** `ads/get` — допустимы ТОЛЬКО: AdCategories, AgeLabel, AdGroupId, CampaignId, Id, State, Status, StatusClarification, Type, Subtype. TextAd, MobileAppAd и т.д. НЕЛЬЗЯ.
- **Директ API:** GeoRegion children часто пустые. Использовать `client.get_regions(search=...)` вместо `get_dictionaries`.
- **Директ API:** активация кампании из DRAFT → ENABLED может требовать `update_campaigns` (множественное число) или веб-интерфейс.

## Ссылки

- Сервис Direct API: `/home/neo/workspace/yandex-direct-api/`
- Сервис Wordstat API: `/home/neo/workspace/wordstat-api/`
- Документация Директ API: https://yandex.ru/dev/direct/doc/ru/
- Документация Wordstat API: https://yandex.cloud/ru/docs/search-api/api-ref/wordstat
- AI Studio (API ключи): https://aistudio.yandex.ru/