# SVG-зображення карт

`/v1/render/*` повертає карту як готовий SVG: натальне колесо, бі- і трі-колесо, композит, ведичні карти (північна, південна, східна), сітку аспектів, космограму, фазу Місяця, таймлайн, біоритми, смугу затемнення і зоряну карту. Ви надсилаєте дані народження, ми рахуємо карту і малюємо її. Повний перелік маршрутів і параметрів у [довіднику API](/docs/api/).

Той самий код малювання опубліковано як npm-пакет [`@astroway/render`](https://www.npmjs.com/package/@astroway/render): якщо дані карти у вас уже є, колесо можна намалювати у браузері чи на своєму сервері, і воно збігатиметься з тим, що повертає API, байт у байт. Версію малювання API повертає в заголовку `X-Render-Version`.

## Запит

```bash
curl -X POST https://api.astroway.info/v1/render/wheel-western \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,
       "options":{"theme":"css","format":"svg"}}' > wheel.svg
```

`format: "svg"` віддає сам файл, типовий `json` загортає рядок SVG у звичайну відповідь API. Теми: `light`, `dark`, `console` і `css`.

## Тема css: кольори вашого сайту

З `theme: "css"` кожен колір у SVG записано як змінну CSS із кольором світлої теми як запасним, наприклад `var(--aw-ring, #222)`. Вставте SVG у HTML сторінки (не в `<img>`: туди змінні не проходять) і задайте змінні:

```css
.chart {
  --aw-chart-bg: transparent;
  --aw-ring: #444;
  --aw-fg: currentColor;
  --aw-aspect-tense: crimson;
}
```

Без жодної змінної карта виглядає точно як `light`. Правило CSS вашої сторінки сильніше за змінну, тож окремий елемент можна перефарбувати класом.

| Змінна | Що фарбує |
|---|---|
| `--aw-chart-bg` | фон карти |
| `--aw-fg`, `--aw-muted` | гліфи і підписи, другорядний текст і поділки |
| `--aw-ring` | кола і лінії сітки |
| `--aw-houses-fill` | поле ведичної карти, диск зоряної карти, мапа затемнення |
| `--aw-benefic` | планети зовнішнього кола, лагна у ведичній карті, події таймлайну без власного кольору |
| `--aw-malefic` | знак ретроградності ℞, смуга затемнення |
| `--aw-aspect-harmonious`, `--aw-aspect-tense`, `--aw-aspect-neutral`, `--aw-aspect-minor`, `--aw-aspect-quintile` | лінії і символи аспектів |
| `--aw-moon-shadow`, `--aw-moon-light` | фаза Місяця |
| `--aw-cycle-physical`, `--aw-cycle-emotional`, `--aw-cycle-intellectual` | біоритми |

## Класи і data-атрибути

У темі `css` західні колеса (`wheel-western`, `bi-wheel`, `tri-wheel`, `composite`) і сітка аспектів мають сталі класи. Назви лише додаються, ніколи не перейменовуються, тож на них можна писати стилі й скрипти.

- Колесо: `aw-bg`, `aw-ring`, `aw-sign aw-sign-leo`, `aw-sign-line`, `aw-tick`, `aw-house-cusp`, `aw-house-number`, осі `aw-axis aw-asc` (`aw-dsc`, `aw-mc`, `aw-ic`), їхні підписи `aw-label aw-axis-label`, заголовок `aw-title`.
- Планета: група `<g class="aw-planet aw-planet-sun">`, ретроградна має ще `aw-retrograde`, планети зовнішнього кола `aw-layer-1`. Усередині `aw-glyph`, `aw-retro` (знак ℞) і `aw-planet-tick`.
- Аспект: лінія `aw-aspect aw-aspect-trine`, лінія між двома картами ще й `aw-cross-aspect`.
- Сітка аспектів: `aw-grid-header`, `aw-grid-cell`, `aw-aspect aw-aspect-square`, `aw-orb`.

Група планети має `data-planet` (`sun`, `north-node`, `lilith`; на зовнішньому колі `b-sun`, на третьому `c-sun`) і `data-label` з назвою і положенням: `Mercury 8°00' Taurus, retrograde`. Лінія аспекту і клітинка сітки мають `data-a` і `data-b`. Так підсвічуються всі аспекти планети при наведенні:

```js
svg.querySelectorAll('.aw-planet').forEach((g) => g.addEventListener('mouseenter', () => {
  const id = g.dataset.planet;
  svg.querySelectorAll('.aw-aspect').forEach((line) =>
    line.classList.toggle('is-on', line.dataset.a === id || line.dataset.b === id));
}));
```

## Свої підписи: labels

Західні колеса приймають `options.labels`: ваші слова для підписів осей, для `<title>` і `<desc>`, які читають екранні читачі, і для назв у `data-label`. Ключі, яких немає, лишаються англійською; самі ми нічого не перекладаємо.

```json
"options": {
  "theme": "css",
  "labels": {
    "asc": "Асц", "mc": "МС", "title": "Натальна карта",
    "bodies": { "Sun": "Сонце", "Moon": "Місяць" },
    "signs": ["Овен","Телець","Близнюки","Рак","Лев","Діва","Терези","Скорпіон","Стрілець","Козеріг","Водолій","Риби"],
    "retrograde": "ретроградний"
  }
}
```

`bodies` має ключі англійською (`Sun`, `North Node`), `signs` це рівно дванадцять назв, починаючи з Овна, кожен підпис до 40 символів.

## Аспекти між двома картами

`/v1/render/bi-wheel` з `options.crossAspects: true` малює пунктиром аспекти між внутрішньою і зовнішньою картою, той самий набір, що `POST /v1/synastry` повертає як `crossAspects`. Пара, де одне з тіл не намальовано, пропускається. Типово вимкнено.

## Готова карта замість даних народження

Якщо карта у вас уже є, бо ви щойно викликали `POST /v1/chart`, надішліть її `data` у поле `chart` замість даних народження, і ми лише намалюємо її. Так працюють `wheel-western`, `aspect-grid` і `bi-wheel` (там `natal.chart` і `outer.chart`, обидві мають бути готовими картами). Зображення вийде байт у байт таким самим, як з даних народження.

```json
{ "chart": { "planets": [ ... ], "houses": { "cusps": [ ... ], "ascendant": 7.77, "mc": 277.12 }, "aspects": [ ... ] },
  "options": { "theme": "css" } }
```

Зайві поля відповіді можна не вирізати. Перевіряється те, що малюється: від 1 до 30 тіл, довготи від 0 до 360, рівно 12 куспидів. Тіло, де є і `chart`, і дані народження, відхиляється з 400.

## Вартість

Виклик `/v1/render/*` з даними народження коштує 10 кредитів, бо карта рахується. З готовою картою `chart` виклики `/v1/render/wheel-western`, `/v1/render/aspect-grid` і `/v1/render/bi-wheel` коштують 1 кредит. Тема, класи і підписи на ціну не впливають.