API

Tuvelia API'si, başka bir uygulamanın (ör. bir WordPress eklentisinin ya da
kendi betiğinin) projelerini, grafiklerini ve haritalarını okumasını, yeni
proje, grafik ve harita oluşturmasını ve bir anahtarla oluşturduğu grafiklerin
ve haritaların verisini ve ayarlarını değiştirmesini sağlar. API ile hiçbir şey silinmez ve yayınlanmaz: yayın her
zaman Tuvelia'da, elle yapılır.

API şu an önizlemede. Tuvelia'nın kendi WordPress eklentisi yayınlanana
kadar uçlar ve alanlar değişebilir; alan kaldırmak ve ad değiştirmek de buna
dahildir. Her değişiklik, tarihiyle birlikte bu sayfanın sonundaki
Değişiklik günlüğü bölümüne yazılır. Önizleme bitince sürüm kuralı
yürürlüğe girer ve v1 içinde yalnız ekleme yapılır.

Kimlik

Her istek bir API anahtarı taşır. Anahtarı Hesap › API anahtarları
sayfasında oluşturursun (API anahtarları) ve
isteğe şu başlıkla eklersin:

Authorization: Bearer tuv_pat_…

Anahtar, oluşturan hesabın verisini okur ve yazar; başka bir hesabın projesini
göremez. Sözleşmenin tanıdığı tek kimlik yöntemi API anahtarıdır.

Uç noktalar

Bütün adresler https://tuvelia.com/api/v1 ile başlar.

Kimlikler UUID biçimindedir (ör. 3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b).
Coğrafya kimlikleri bunun DIŞINDADIR: onlar de-adm2 gibi kısa anahtarlardır.
Bu sürümde grafikler ve haritalar okunabilir ve yazılabilir. Hikâyeler listede
yer almaz.

Örnek:

curl -H "Authorization: Bearer tuv_pat_…" https://tuvelia.com/api/v1/projects

{
  "projects": [
    { "id": "3f2b8c1e-…", "name": "Haber grafikleri", "createdAt": "2026-09-02T12:00:00.000Z" }
  ]
}

Zamanlar ISO 8601 biçiminde ve UTC'dir.

Yayındaki grafiği ya da haritayı gömmek

Grafik ve harita yanıtlarında, listede de tek öğe okumasında da, yayındaki
öğenin published alanı doludur; yayında olmayan öğede bu alan nulldır.
published.urls üç adres taşır:

• live: etkileşimli, canlı çizim. <iframe> ile gömmek için budur; ipucu
  kutuları ve zaman imleci çalışır. Her zaman doludur.
• page: grafiğin tek başına açılan sayfası. null olabilir.
• svg: grafiğin durağan görüntüsü. null olabilir.

page ve svg durağan görüntüye dayanır. Bir yayında durağan görüntü yoksa bu
iki adres çalışmaz; API o durumda adres uydurmaz, null döner. Programın bu
ikisini kullanmadan önce dolu olup olmadığına bakmalı; live her yayında
çalışır.

Hazır gömme kodu (oEmbed). live adresini kendin <iframe>e koymak
yerine oEmbed ucundan hazır kodu alabilirsin. Kod Tuvelia'daki Paylaş ›
Bağlantı ve embed penceresinin verdiğiyle aynıdır: oranı doğrudur, zamanlı
öğede imleç şeridine yer açar, telefonda kutuyu uzatır. Bu uç anahtar istemez,
yalnız yayındaki içeriği verir:

GET https://tuvelia.com/oembed?url=https://tuvelia.com/embed/{publicId}/live&format=json

Yanıt oEmbed biçimindedir (type: "rich", html, width, height, title).
url olarak /embed/{publicId} adresini de verebilirsin. İsteğe bağlı
maxwidth ve maxheight yalnız bildirilen ölçüyü küçültür; kodun kendisi
zaten sayfanın genişliğine uyar. WordPress gibi oEmbed tanıyan sistemler bu
ucu gömme sayfasındaki keşif bağlantısından da bulur.

Yayındaki görüntü, öğe Tuvelia'da yeniden yayınlanana kadar değişmez. API ile
verisini değiştirdiğin bir grafik ya da harita da öyledir: yeni veri, öğeyi
Tuvelia'da yeniden yayınladığında görünür. published.stale bunu söyler:
true ise öğede yapılan değişiklikler gömülü görüntüde henüz görünmüyor. API
yayınlayamaz; kullanıcının Tuvelia'da Yeniden yayınla demesi gerekir.

Grafiğin içeriği

GET /charts/{chartId} yanıtında data tablo biçimindedir: headers sütun
başlıklarıdır (ilki kategori sütunu), rows satırlardır. Her hücre METİN
olarak gelir, sayılar da; boş hücre "ölçüm yok" demektir, sıfır değil.

⚠ Ondalık ayırıcı NOKTADIR ("64.8"). Virgüllü yazım ("64,8") sayı
sayılmaz: o hücre sıfır olarak çizilir ve grafik boş görünebilir. Sayıların
ekranda nasıl yazılacağı ayrı bir ayardır (grafik ayarlarındaki sayı biçimi);
gönderdiğin veriyi etkilemez.

title grafiğin Tuvelia'daki adıdır, yani proje listesinde gördüğün ad.
Grafiğin üstünde görünen başlık bu değil, config.title alanıdır; ikisi
farklı olabilir.

config grafiğin görünüm ayarlarıdır: grafik tipi (chartType), renkler,
eksenler, notlar, künye. Ayar alanları zamanla çoğalır; tanımadığın alanları
yok say.

config içinde neye söz veriliyor. Sürüm kuralı config nesnesinin
tamamını değil, şu alanları kapsar: chartType, title, subtitle,
sourceName, sourceLink. Nesnedeki diğer ayarlar Tuvelia'nın iç ayarlarıdır:
okuyabilir ve geri yazabilirsin, ama haber verilmeden değişebilirler.
Programını onlara bağlama.

Yanıtta üç alan daha vardır:

• version: içerik sürümü. Veri ya da ayar her değiştiğinde artar.

• apiManaged: grafiğin bir API anahtarıyla oluşturulmuş olduğunu söyler;
  alanın anlamı budur. Bugünkü kural gereği anahtar yalnız true olan
  grafikleri değiştirebilir. Grafik listesinde de bu alan vardır.

• warnings: verinin bir kısmı çizilmiyorsa uyarılar, yoksa boş dizi. Örneğin
  ağaç haritası boş, sıfır ya da eksi değerli satırları çizemez; yarış aynı anda
  sınırlı sayıda varlık gösterir. Her uyarı bir code, çizilmeyenlerin sayısı
  (count) ve Türkçe bir açıklama (message) taşır. Veri silinmez, yalnız
  çizilmez.

  En önemlisi nothing_drawn: grafiğin hiçbir öğesi çizilmiyor demektir.
  Yarış, dağılım, süre çizelgesi ve ağaç haritası bir eşleme olmadan boş çizilir
  (ör. yarış için config.temporal); uyarı hangi ayarın eksik olduğunu ve varsa
  hangi template ile hazır kurulacağını söyler. Bu uyarıyı gördüğünde grafik
  oluşturma isteği başarılı olmuştur ama grafik boştur.

  Bir uyarı da sayı biçimiyle ilgilidir: comma_decimal_cells, virgüllü ondalık
  taşıyan ("12,5") ve bu yüzden sıfır çizilen hücreleri sayar. Veri yazarken
  ondalık ayırıcı noktadır; bu uyarıyı görüyorsan gönderdiğin sayılar grafikte
  görünmüyor demektir.

Haritanın içeriği

GET /maps/{mapId} yanıtında veri iki biçimde gelir ve aradaki fark önemlidir:

• rawRows — haritanın ham kaynağı: { "input": "Ankara", "value": "806.2" }.
  Bölge adı yazıldığı gibi durur ve coğrafyada karşılığı bulunamayan satırlar da
  buradadır.
• data — haritada gerçekten çizilen satırlar: { "id": 6, "value": 806.2, "label": "Ankara" }. Bölge adı coğrafyanın sayısal kimliğine çözülmüştür.

Eşleşmeyen bir satır rawRowsta vardır ama datada yoktur. Bu yüzden veriyi
okuyup değiştirmek istersen rawRowsu temel al: datadan türetip geri
yazmak, eşleşmeyen satırları sessizce silerdi.

Zamanlı haritalarda her satırda bir at alanı bulunur:
{ "precision": "year", "iso": "1985" }. isonun biçimi precisiona bağlıdır
(year → 1985, month → 1985-03, day → 1985-03-17). Yıllık bir veriyi
1985-01-01 diye yazmak, eksende olmayan bir gün kesinliği uydurur.

config haritanın ayarlarıdır. Sözleşmenin kapsadığı alanlar geographyId
(hangi coğrafya), view (kapsam), meta (künye) ve temporal (zaman beyanı);
diğerleri Tuvelia'nın iç ayarlarıdır.

Harita coğrafyaları ve kapsam

Bir haritanın altlığı config.geographyId ile seçilir. Geçerli değerleri
GET /geographies listeler; her satır coğrafyanın adını, ait olduğu ülkeyi ve
idari düzeyini verir.

Kapsam (config.view.scope) haritanın yalnız bir bölümünü çizmeye yarar ve iki
türü vardır:

• Üst birime göre — { "parentId": 15 } yalnız o üst birimin alt
  birimlerini çizer (ör. bir eyaletin ilçeleri). Yazılabilecek değerleri
  GET /geographies/{geographyId}/scope-parents listeler; her satır üst birimin
  adını ve seçilirse çizilecek bölge sayısını verir. Bu keşif ucu gereklidir:
  bazı coğrafyalarda yüzlerce üst birim vardır ve hata mesajı hepsini sayamaz.
  Coğrafyanın parentGeographyId alanı null ise bu tür kapsam kullanılamaz.
• Kimlik listesine göre — { "ids": [233, 428, 440] } yalnız o bölgeleri
  çizer ve her düzeyde çalışır. Hazır çok ülkeli listeler için
  GET /region-presetse bak: yanıttaki ids değerini olduğu gibi kullan,
  listenin adını değil. Liste ileride değişirse adı kaydedilmiş bir harita
  sessizce başka bir şey gösterirdi.

Harita oluşturmak ve veri yazmak

Harita iki adımda kurulur ve bu bilinçli: bölge adlarının coğrafyaya
çözülmesi ayrı bir iştir ve eşleşme raporunu veri ucu döndürür.

1. Haritayı oluştur — veri göndermezsin, harita boş doğar:

POST /projects/{projectId}/maps
{ "title": "İllere göre nüfus", "config": { "geographyId": "tr-adm1" } }

geographyId değerlerini GET /geographies listeler. Projeksiyon coğrafyadan
türetilir; harita hesabının varsayılan marka kitini giyer. Yanıt 201 ve
Location başlığıyla gelir.

2. Veriyi yaz — bölge adlarını gönderirsin, sunucu çözer:

PUT /maps/{mapId}/data
{
  "rows": [
    { "region": "Ankara", "value": "5803" },
    { "region": "İstanbul", "value": "15907" }
  ]
}

Değerler metin olarak gönderilir ve ondalık ayırıcı noktadır ("806.2");
binlik ayırıcı kullanılmaz ("4946", "4.946" değil). Sütunun geri kalanı
kanıtlarsa virgüllü ondalık çevrilir (806,2 → 806.2). Belirsiz (4.946,
1,234) ya da sayı olmayan değerler yanıtta uyarıyla bildirilir; sayı olmayan
değer (abc, N/A) çizilmez, boş değer 0 sayılır.
Zamanlı harita için her satıra at eklersin:
{ "region": "Ankara", "value": "5803", "at": { "precision": "year", "iso": "2026" } }.
Zaman beyanı (config.temporal) at taşıyan satırlardan türetilir, ayrıca
göndermen gerekmez; hassasiyet ilk zamanlı satırınkidir. Zamanlı bir haritada
at taşımayan ya da hassasiyeti farklı olan satır reddedilmez: kaydedilir
ama çizilmez ve yanıtın warnings alanında undeclared_period_rows koduyla
adıyla sayılır. Hiçbir satırda at yoksa harita zamansızdır.

Eşleşmeyen satırlar sessizce düşmez. Bir bölge adı coğrafyada bulunamazsa ya
da haritanın kapsamı dışında kalırsa satır kaydedilir (rawRows'ta durur) ama
çizilmez, ve yanıtın warnings alanında adıyla sayılır:

"warnings": [
  { "code": "unmatched_rows", "count": 1,
    "message": "1 bölge adı bu coğrafyada bulunamadı: Lefkoşa. …" }
]

Uyarı kodları: unmatched_rows (ad çözülemedi) · mixed_id_types (ad ile kod
aynı veride karışık; bu yüzden bulunamayan satırlar) · out_of_scope_rows
(kapsam dışı) · matched_not_drawable (bu geometride yok) ·
undeclared_period_rows (satırın anı haritanın dönemlerinde yok — zamanlı
haritada at eksikse de bu gelir) · duplicate_rows (aynı bölge ya da
bölge+an için birden fazla değer; yalnız biri çizilir) · unreadable_values
(sayı değil, çizilmez) · ambiguous_number_cells (binlik mi ondalık mı
belirsiz) · comma_decimal_cells (virgüllü ondalık noktalıya çevrildi) ·
scheme_hidden_by_colors (renk şeması değişti ama katmandaki colors onu
gizliyor; yalnız PATCH yanıtında).

Hangi ayarlar var? GET /map-options hepsini listeler: adı, türü, ne işe
yaradığı ve seçenekli olanlarda (renk şeması, projeksiyon, lejant köşesi…)
geçerli değerlerin tamamı. Bir ayarı değiştirmeden önce buraya bakmak, geçersiz
bir değer gönderip 400 almaktan hızlıdır.

⚠ Renk şeması, basamak sayısı ve "veri yok" rengi layers dizisinin
içindedir (layers[].colorScale.scheme gibi). Bu dizi bütün olarak yazılır:
tek bir alanı değiştirmek için haritayı oku, katman nesnesini kopyala, alanı
değiştir ve layersı tamamen geri gönder — eksik gönderdiğin alanlar kaybolur.

⚠ config.dataSource (konnektör künyesi) API ile yazılamaz. O blok verinin
hangi kaynaktan, hangi lisansla geldiğini söyleyen bir köken iddiasıdır ve
lisansı haritanın künyesine basılır; tek meşru yazarı Tuvelia'daki "Kaynaktan
veri" akışıdır. Kaynağı belirtmek için config.meta.source alanına serbest
metin yaz.

Ayarları değiştirmek için PATCH /maps/{mapId} kullanırsın; yalnız
gönderdiğin alanlar değişir. ⚠ geographyId değiştirirsen kapsam (view)
sıfırlanır — aynı çağrıda açıkça view göndermediysen. Sebebi: 15 Almanya'da
bir eyalet, başka bir ülkede başka bir bölgedir.

Haritalarda da anahtar yalnız anahtarla oluşturulan haritaları değiştirir;
Tuvelia'da oluşturduğun haritalar okunur ama değiştirilemez. expectedVersion
gönderirsen araya giren bir değişiklik yazımı conflict (409) ile reddeder.

Proje ve grafik oluşturmak

Yazma isteklerinin gövdesi JSON'dır ve Content-Type: application/json
başlığı zorunludur. Gövdede tanınmayan bir alan varsa (ör. yazım hatası) istek
reddedilir; alan sessizce yok sayılmaz.

Proje oluşturmak için adını gönderirsin:

curl -X POST https://tuvelia.com/api/v1/projects \
  -H "Authorization: Bearer tuv_pat_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Seçim grafikleri" }'

Yanıt 201 durumuyla projeyi döner. Proje adı en çok 200 karakter olabilir.

Grafik oluşturmak için bir ad ve genellikle veri gönderirsin:

curl -X POST https://tuvelia.com/api/v1/projects/{projectId}/charts \
  -H "Authorization: Bearer tuv_pat_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Yıllık enflasyon",
    "data": { "headers": ["Yıl", "TÜFE"], "rows": [["2023", "64.8"], ["2024", "44.4"]] },
    "config": { "chartType": "line", "sourceName": "TÜİK" }
  }'

Yanıt 201 durumuyla grafiği döner; Location başlığı grafiğin adresini
taşır. Oluşturulan grafik için şunları bil:

• Hesabının varsayılan marka kitini giyer: renkleri ve yazı tipi Tuvelia'daki
  Yeni öğe ile oluşturduğun bir grafikle aynıdır.
• Veri gönderir ve config.title vermezsen grafiğin görünen başlığı grafiğin
  adıdır, alt başlığı boştur. Veri göndermezsen grafik örnek veriyle ve o
  örneğin kendi başlığıyla oluşur; gerçek veriyi sonra PUT ile verirsin.
• template alanı üç başlangıç şablonundan birini seçer: race (yarış),
  scatter (dağılım) ya da timeline (süre çizelgesi). Bu tipler veri eşlemesi
  olmadan boş çizer; şablon onları çalışır hâlde kurar. Gönderdiğin data ve
  config şablonun üzerine yazar.
• configte GET /charts/{chartId} yanıtındaki ayar alanlarını kullanırsın.
  Notlar (annotations) API ile yazılamaz; notları Tuvelia'da eklersin.
• Veri sınırları Tuvelia'dakiyle aynıdır: en çok 30 sütun, 5.000 satır, hücre
  başına 300 karakter.

Grafik yayınlanmaz. Gömmek için onu Tuvelia'da bir kez yayınlarsın.

Grafiği güncellemek

Bir API anahtarı YALNIZ anahtarla oluşturulmuş grafikleri (apiManaged: true)
değiştirebilir. Hesabının herhangi bir anahtarı bunu yapabilir; anahtarı
yenilediğinde uygulaman o grafikleri güncellemeye devam eder. Tuvelia'da
oluşturduğun grafikler anahtarla okunur ama değiştirilemez; istek 403
forbidden alır.

• PATCH /charts/{chartId} gövdesinde config taşır ve yalnız gönderdiğin
  alanları değiştirir. Grafik tipini de böyle değiştirirsin:
  { "config": { "chartType": "bar" } }.
• PUT /charts/{chartId}/data gövdesinde data taşır ve verinin tamamını
  yeniden yazar; ayarlar değişmez.

İkisi de güncellenen grafiği döner.

Arada değişen grafiğin üzerine yazmamak. Grafik bu arada Tuvelia'da
değişmiş olabilir. İstersen gövdeye son okuduğun sürümü eklersin:

{ "data": { … }, "expectedVersion": 7 }

Grafiğin sürümü artık 7 değilse yazma yapılmaz ve yanıt 409 conflict
olur; mesaj güncel sürümü söyler. Grafiği yeniden okur, değişikliğini güncel
hâline uygular ve tekrar gönderirsin. expectedVersion göndermezsen son yazan
kazanır.

Anahtarla yapılan her yazma, hangi anahtarla, ne zaman ve hangi proje ya da
grafik üzerinde yapıldığıyla kayda geçer. Kayıt içeriği (veriyi, ayarları)
tutmaz ve 90 gün saklanır.

Hatalar

Hata yanıtı her zaman aynı biçimdedir:

{ "error": { "code": "not_found", "message": "Grafik bulunamadı (id=…). …" } }

Programın codea bakmalı; message insan için yazılmış Türkçe bir
açıklamadır ve değişebilir.

İleride yeni kodlar eklenebilir; tanımadığın kodu HTTP durumuna göre ele al.

Hız sınırı

Okuma istekleri hesap başına 10 dakikada 300, yazma istekleri ayrıca 10
dakikada 120 ile sınırlıdır. Okumanın ve yazmanın bütçeleri birbirinden
bağımsızdır; hesabın bütün anahtarları bu bütçeleri paylaşır. Sınır aşılınca
yanıt 429 olur ve Retry-After başlığı kaç saniye bekleyeceğini söyler.

Bir yazma isteğinin gövdesi en çok 2 MB olabilir; daha büyüğü 413 alır.

Buradaki sayılar söz değildir ve değişebilir. Programın her durumda 429 ve
413 yanıtlarını karşılayabilmeli.

OpenAPI belgesi

API'nin makinece okunur tarifi şu adrestedir ve kimlik istemez:

https://tuvelia.com/api/v1/openapi.json

Belgeyi Postman gibi araçlara ya da bir ChatGPT eylemine (Actions) adresiyle
aktarabilirsin.

Sürüm kuralı

Şimdi (önizleme). API önizlemede olduğu sürece uçlar ve alanlar
değişebilir: bir alan kaldırılabilir, adı ya da anlamı değişebilir. Böyle bir
değişiklik önce aşağıdaki Değişiklik günlüğüne yazılır. Gereksiz değişiklik
yapılmaz; amaç, sözleşmeyi ilk gerçek kullanıcısı olan WordPress eklentisiyle
sınamak.

Önizleme bittikten sonra. v1 içinde yalnız ekleme yapılır: yeni uç ya da
yanıtlara yeni alan. Var olan bir alan silinmez, adı ya da anlamı değişmez;
böyle bir değişiklik /api/v2 olarak gelir.

Her iki dönemde de istemcin tanımadığı alanları ve tanımadığı hata kodlarını
yok saymalı.

Değişiklik günlüğü

• 2026-10-08 — grafik ayarında smallMultiplesAxisTitles (Tuvelia'nın iç ayarı): küçük çoklu
  panellerinin dikey eksen başlıkları, [{ panel, title }] — panel adı seri ya da kategori adı, başlık en
  çok 80 karakter, en çok 200 başlık. Veride olmayan panel ve aynı panele ikinci başlık 400. Başlıklar
  translations.{dil}.labels ile çevrilir. OpenAPI 1.0.0-preview.34.
• 2026-10-08 — grafik translations içinde labels: seri ve kategori ADLARININ çevirisi.
  { "en": { "labels": { "Güney Kore": "South Korea", "Ar-Ge (%GSYH)": "R&D (% of GDP)" } } } —
  anahtar ana dildeki ad (TAM eşleşme), değer o dildeki ad; en çok 2.000 ad. O dilin canlı gömmesinde,
  görselinde, PDF'inde ve videosunda grafiğin her yerinde (kart başlığı, eksen, vurgu, hücre notu,
  gizleme) bu ad kullanılır; veri ana dilde kalır. İsteğe bağlı; translations yine BÜTÜN yazılır.
  Yalnız ad çevirisi olan dil de published.urls.liveByLocaleda görünür. OpenAPI 1.0.0-preview.33.
• 2026-10-08 — grafik ayarında küçük çoklu alanları (Tuvelia'nın iç ayarları; söz verilen alanlar
  değişmedi): smallMultiplesColumns artık 2–6 · smallMultiplesScale (shared | independent) ·
  highlight ({ category, color }) · cellNotes ([{ category, series, text }], en çok 200).
  highlight ve cellNoteste veride olmayan ad ve aynı hücreye ikinci not 400 ile reddedilir (mevcut
  adlar mesajda sayılır).
• 2026-10-05 — published.urls.liveByLocale eklendi. Tek grafik ve tek harita
  yanıtlarında, ana dil dışında en az bir alanı çevrilmiş her dil için canlı adres:
  { "en": "https://tuvelia.com/embed/{id}/live/en" }. live ana dildir; çeviri yoksa
  alan hiç gelmez. Durağan görüntü (page, svg) yalnız ana dildedir. oEmbed ucu
  …/live/{dil} adresini de kabul eder.
• 2026-10-05 — grafik ve harita ayarında translations eklendi (aynı öğede iki dil).
  İsteğe bağlı; anahtar dil (en), değer { fields: { … } }. Grafikte alanlar:
  title · subtitle · xAxisTitle · yAxisTitle · tooltipLabel · valuePrefix ·
  valueSuffix · sourceLabel · sourceName · dataAsOf · footerText; haritada:
  title · legendTitle · sourceLabel · source · note. locale ana dildir; ana
  dilin metinleri kendi alanlarında kalır. Bilinmeyen alan ya da dil reddedilir, metin en
  çok 500 karakter. Alan bütün yazılır (bir dili güncellerken önce oku, birleştir,
  tamamını gönder). Yayın ve dışa aktarma bugün ana dilde üretilir.
• 2026-10-05 — grafik ayarında locale eklendi. İsteğe bağlı locale: "tr" | "en"
  (yoksa tr): grafiğe sistemin bastığı metinlerin dili — künye etiketleri (Veri
  tarihi/Data as of · Oluşturulma/Created · Güncellenme/Updated · Lisans/License ·
  Atıf/Cite), boş tuval yazısı, pasta/ağaç haritası ipucu satırları, künye
  tarihlerinin ve zaman ekseninin ay adları, yüzde işaretinin yeri (%25 / 25%).
  Sayı biçimi numberFormatta kalır. sourceLabel ve tooltipLabel kayıtlı
  metinlerdir; dili değiştirirken eski dilin varsayılanını taşıyorlarsa yenisini
  (Source/Value) de gönder. GET /chart-options alanı listeler. Ayrıca pasta
  ipucundaki yüzde artık grafiğin ondalık ayracını kullanır (Türkçe biçimde
  eskiden %25.0 yazıyordu).
• 2026-10-05 — harita ayarında locale eklendi. İsteğe bağlı locale: "tr" | "en"
  (yoksa tr): haritaya sistemin bastığı metinlerin dili — künye ön ekinin
  varsayılanı (Kaynak/Source; meta.sourceLabel yazılmışsa o kalır), "veri yok"
  yazıları, sınır atfının öneki, dönem adları ve büyük sayı kısaltma harfleri (tr
  B/Mn/Mr = bin/milyon/milyar · en K/M/B). Başlık, kaynak adı, not ve bölge
  adları çevrilmez; sayı ayraçları değişmez. GET /map-options alanı listeler.
• 2026-09-24 — boş hücre artık hiçbir tipte 0 çizilmez. Çizgi ve alan boş
  hücrede kopar, çubuk ve yığın o hücreye çubuk/dilim çizmez (yığının boyu yalnız
  dolu hücrelerin toplamı). empty_cells uyarısının mesajı buna göre değişti
  ("0 olarak çiziliyor" yerine tipe göre etki); kod ve sayım aynı. Sayıya
  çevrilemeyen metin boş sayılmaz, comma_decimal_cells ile sıfır çizilmeye devam
  eder.
• 2026-09-24 — yeni uyarı kodu empty_cells. Grafiğin çizdiği değer
  hücrelerinden boş olanlar (boş, boşluk ya da -) sayılır; mesaj tipe göre ne
  olduğunu söyler (o gün çubuk/çizgi/alan/yığında 0 çiziliyordu — yukarıdaki kayıt;
  pastada dilim, piramitte kanat, dumbbell'da çift düşer). Piramidin yüzde modunda tek kanadı boş olan
  kategori artık hiç çizilmez (eskiden dolu kanat %100 çiziliyordu). warnings[].code
  açıklaması artık bütün kodları sayar (nothing_drawn ve comma_decimal_cells
  eksikti).
• 2026-09-24 — decimalMode eklendi. Grafik ayarında isteğe bağlı
  decimalMode: "auto" | "fixed". auto fazla basamağı gösterimde kırpar
  (|değer| ≥ 1 ise en çok 2 ondalık, küçük değerlerde 2 anlamlı basamak);
  fixed decimalPlacesi aynen uygular (0 = tam sayıya yuvarla). Alan yoksa
  decimalPlaces > 0 ise fixed, 0 ise auto sayılır. Önceden decimalPlaces: 0
  hiç yuvarlamıyordu ve Türkçe biçimde ondalık noktayla yazılıyordu.
• 2026-09-24 — styleId değişimi değiştirilmiş alanları korur. Stil
  değiştiğinde krom renkleri, fontFamily, borderRadius ve depth yalnız
  önceki stilin varsayılanında duruyorsa yeni stile geçer; marka kitinden ya da
  elle yazılmış değer korunur. Seçilen depth yeni stil ve tipte kapalıysa yeni
  stilin derinliği yazılır. Önceden stil değişimi bu alanların hepsini yeniden
  yazıyordu.
• 2026-09-24 — showFooter artık kaynağı gizlemiyor. showFooter: false
  yalnız künyenin dipnot kısmını (veri tarihi, oluşturma/güncelleme tarihi, not
  metni, atıf düğmesi, marka satırı) gizler. Kaynak adı ve lisans yalnız
  showSource ile yönetilir. Önceden showFooter: false kaynak ve lisansı da
  gizliyordu; bu grafiklerde kaynak artık görünür.
• 2026-09-23 — harita colorScale.mode açıklaması düzeltildi (belge
  düzeltmesi). Açıklama "threshold sınırları domainden okur" diyordu; bu,
  eşiklerin elle verilebileceğini düşündürüyordu. Doğrusu: threshold bugün
  quantize ile aynı çizer — en küçük ile en büyük değer (domain ya da veri)
  arasını eşit basamaklara böler; elle eşik girişi yoktur. Davranış değişmedi.
• 2026-09-23 — sortOrder açıklaması düzeltildi (belge düzeltmesi).
  Açıklama yalnız ağaç haritasının bu ayarı yok saydığını söylüyordu; aslında
  kendi sırasını kuran beş tip yok sayıyor: diverging (veri sırası) ·
  treemap (büyükten küçüğe) · race (her an değere göre) · scatter (konum
  değerden gelir) · timeline (zamana göre). Davranış değişmedi; yalnız
  açıklama doğru oldu.
• 2026-09-23 — grafikte "değere göre" renk. config.colorMode yeni bir
  değer alıyor: value. Tek serili bar ve pie grafikte her çubuk ya da
  dilim değerine oranlı boyanır; en küçük değer rampanın en açık, en büyük
  değer en koyu rengini alır. Rampa colorPreset ile seçilir (Pastel rampa
  değildir, Okyanus kullanılır). Başka her grafikte value, preset gibi
  davranır. Ekleme yapıldı; var olan değerlerin anlamı değişmedi.
• 2026-09-22 — hazır gömme kodu için oEmbed ucu. Yeni, anahtarsız uç
  GET https://tuvelia.com/oembed?url={yayın adresi}: yayındaki bir grafiğin,
  haritanın, karşılaştırmanın ya da anlatı çizelgesinin gömme kodunu Tuvelia'nın
  paylaşım penceresindeki kodla aynı biçimde döndürür. /api/v1 altında değildir
  ve bir oEmbed standardı ucudur. Yayın bilgisindeki (published) açıklamalar
  artık yalnız grafiği değil haritayı da anlatıyor. Ekleme yapıldı; var olan
  hiçbir uç değişmedi.
• 2026-09-22 — grafik künyesi Türkçe; yeni grafiklerde kaynak etiketi
  Kaynak. sourceLabel verilmeden oluşturulan grafikler artık Kaynak
  ile başlar (eskiden Source); daha önce oluşturulmuş grafiklerin kayıtlı
  etiketi değişmez. Künyedeki sabit etiketler Türkçe basılır: Veri tarihi: ·
  Oluşturulma: · Güncellenme: · Atıf.
• 2026-09-22 — grafikte alt eksen adlarının açısı. Yeni opsiyonel ayar
  xAxis.labelAngle: horizontal (varsayılan, alan yoksa da böyle) ·
  diagonal (45°) · vertical · auto (yatay sığmıyorsa 45°, o da sığmıyorsa
  dikey). Yalnız dikey çubuk, yığılmış, çizgi, alan ve dikey dumbbell'da
  etkilidir. Döndürülmüş adlar alttan yer açar; grafik yüksekliğinin %40'ına
  sığmayan ad "…" ile kısalır. Her grafik tipinin ayar keşfinde görünür.
• 2026-09-22 — haritada "Made with Tuvelia" satırı. Yeni opsiyonel ayar
  showBranding (üst düzeyde, metanın dışında): yoksa açık, false
  gizler. Satır sağ altta, coğrafya atfının sonunda durur; atıf bundan
  bağımsızdır ve gizlenemez. ⚠ Görünüm değişikliği: alanı hiç yazılmamış
  mevcut haritalarda da satır artık görünür ve alt satır payı açılır.
• 2026-09-21 — haritada değer etiketleri. Yeni opsiyonel ayar
  labels.mode: off (varsayılan, alan yoksa da böyle) · all · exports
  (yalnız video, indirilen görsel ve ZIP karelerinde; gömülü haritada ve hikâyede
  yazılmaz). Sığmayan bölgede etiket basılmaz. Nesne bütün yazılır.
• 2026-09-21 — haritada iki yeni ayar: doğal kırılım ve kaynak etiketi.
  layers[].colorScale.mode artık natural değerini de alır: birbirine yakın
  değerleri aynı renk basamağında toplar, tek bir dev değeri kendi basamağına
  ayırır. meta.sourceLabel (opsiyonel, varsayılan Kaynak) künyede kaynağın
  önüne basılan ön ektir; harita ": " ekler. ⚠ Görünüm değişikliği: künye
  artık "Kaynak: TÜİK · not · lisans" biçiminde basılıyor (eskiden ön eksiz ve
  uzun tireyle); meta.source alanına ön eki ayrıca yazma.
• 2026-09-21 — belge düzeltmesi: haritada iç içe ayar nesneleri bütün
  yazılır. PATCH /maps/{mapId} ayarları yalnız üst düzeyde birleştirir;
  meta, legend, scaleBar, locator ve animation gibi iç içe nesneler
  bütün olarak yazılır ve eksik alan reddedilir. Belge bunu artık açıkça
  söylüyor; hata mesajı da eksik alanın adını veriyor. Davranış değişmedi.
• 2026-09-21 — haritanın coğrafyası değişince veri yeniden çözülüyor;
  okuma yanıtı da uyarıları adıyla veriyor. PATCH /maps/{mapId} ile
  geographyId değiştiğinde veri artık yeni coğrafyaya göre yeniden çözülüyor.
  ⚠ Davranış değişikliği: eskiden veri eski coğrafyanın kimlikleriyle
  kalıyordu ve değerler yeni haritada yanlış bölgelere boyanabiliyordu. Ham
  satırı olmayan eski bir kayıtta coğrafya değişimi artık anlaşılır bir hatayla
  reddediliyor. Aynı geographyId'yi yeniden göndermek artık değişim sayılmıyor
  ve kapsamı sıfırlamıyor. GET /maps/{mapId} ve PATCH yanıtlarındaki
  warnings, yazma yanıtıyla aynı kodları ve adları taşıyor; eskiden okuma
  yanıtı her çizilmeyen satırı unmatched_rows diye bildiriyordu. Yeni uyarı
  kodu: scheme_hidden_by_colors.
• 2026-09-21 — harita verisinde sessiz kalan durumlar artık bildiriliyor.
  PUT /maps/{mapId}/data yanıtına dört yeni uyarı kodu eklendi:
  unreadable_values, ambiguous_number_cells, comma_decimal_cells ve
  mixed_id_types. Aynı ad ve dönem iki kez geldiğinde, zamansız haritada da
  aynı bölge iki kez geldiğinde, duplicate_rows artık bildiriliyor.
  ⚠ Davranış değişikliği: sayı olmayan bir değer (abc, N/A) eskiden
  sessizce 0 sayılıp çiziliyordu; artık çizilmiyor ve uyarıyla bildiriliyor.
  Boş değer eskisi gibi 0 sayılıyor.
• 2026-09-21 — belge düzeltmesi: harita verisinde zamanı eksik satır
  reddedilmez. PUT /maps/{mapId}/data açıklaması ve bu sayfa "kısmi zaman
  reddedilir" diyordu; doğru değildi. Zamanlı bir yazımda at taşımayan ya da
  hassasiyeti farklı olan satır kaydedilir, çizilmez ve undeclared_period_rows
  uyarısıyla adıyla sayılır. Davranış değişmedi; yalnız anlatımı düzeltildi.
• 2026-09-21 — harita ayarları keşfedilebilir oldu (GET /map-options) ve
  config.dataSource API'ye kapatıldı. Harita ayarlarının tamamı artık adı,
  türü, açıklaması ve geçerli değerleriyle listeleniyor — renk şeması ve
  basamak sayısı dahil. dataSource bir köken iddiası olduğu ve haritanın
  künyesine basıldığı için API ile yazılamaz hâle geldi; kaynak belirtmek için
  meta.source kullanılır. ⚠ Bu ikincisi kısıtlayıcı bir değişikliktir (önizleme
  kapsamında).
• 2026-09-21 — haritalar yazılabilir oldu (üç yeni uç).
  POST /projects/{projectId}/maps · PATCH /maps/{mapId} ·
  PUT /maps/{mapId}/data. Veri ucu bölge adlarını coğrafyaya çözer ve
  eşleşmeyenleri warnings alanında adıyla sayar. Ekleme yapıldı; var olan
  hiçbir uç değişmedi.
• 2026-09-21 — haritalar okunabilir oldu (beş yeni uç).
  GET /projects/{projectId}/maps · GET /maps/{mapId} · GET /geographies ·
  GET /geographies/{geographyId}/scope-parents · GET /region-presets.
  Harita oluşturma ve düzenleme henüz yok. Ekleme yapıldı; var olan hiçbir uç
  değişmedi.
• 2026-09-20 — yayın bilgisi grafik yanıtına eklendi (published, stale).
  Bir grafiği API ile güncellediğinde yayındaki sürüm geride kalır; yanıt artık
  bunu söylüyor. Yayına gitmek insan onayıyla olur: API ile yeniden
  yayınlanamaz, kullanıcı Tuvelia'da "Yeniden yayınla" demelidir. Ekleme
  yapıldı.
• 2026-09-20 — ayar açıklamaları. GET /chart-options artık her ayarın ne
  işe yaradığını da yazıyor; ayrıca temporal ve legend gibi her tipte
  geçerli ayar blokları alan alan listeleniyor (önce yalnız blok adı
  görünüyordu). Ekleme yapıldı.
• 2026-09-20 — yeni uç: GET /chart-options. Ayarların adları yanıtlarda
  zaten görünüyordu ama seçenekli alanlarda hangi değerlerin geçerli olduğunu
  öğrenmenin yolu denemekti; artık listeleniyor. Ekleme yapıldı.
• 2026-09-20 — yeni uyarı kodu: nothing_drawn. Eşlemesi olmayan yarış,
  dağılım, süre çizelgesi ve ağaç haritası boş çiziliyordu ve yanıt bunu
  söylemiyordu; artık warnings sebebini ve çözümünü bildiriyor. Ekleme
  yapıldı, var olan bir kodun anlamı değişmedi.
• 2026-09-20 — yeni uç: GET /chart-templates. createChartin template
  alanı ilk günden beri vardı ama geçerli kimlikleri öğrenmenin yolu yoktu; artık
  listelenebiliyor. Ekleme yapıldı, var olan hiçbir uç değişmedi.
• 2026-09-20 — yeni uyarı kodu: comma_decimal_cells. Virgüllü ondalık
  taşıyan hücreler sıfır çiziliyordu ve yanıt bunu söylemiyordu; warnings
  artık bildiriyor. Ekleme yapıldı, var olan bir kodun anlamı değişmedi.
• 2026-09-20 — ondalık ayırıcı netleşti. Örnekteki virgüllü sayı noktalıyla
  değiştirildi ve kural açıkça yazıldı: veri alanında ondalık ayırıcı noktadır.
  Davranış değişmedi; belge yanlış yönlendiriyordu (ajan denemesinde görüldü).
• 2026-09-20 — önizleme başladı. API'nin ilk yayını.