Kimlik ve anahtar

Her /v1 isteği X-Api-Key başlığı taşır. Karo sunucusunda anahtar isteğe bağlıdır (Karolar ve stiller).

curl -sS "https://api.updraftmaps.com/v1/sites?bbox=28.5,36.0,30.0,37.2&kind=takeoff" \
  -H "X-Api-Key: $UPDRAFT_API_KEY"

Anahtar almak

Anahtarları Updraft yöneticisi açar, iptal eder ve kotasını ayarlar; kendi kendine kayıt portalı henüz yok. İsterken şunları bildirin:

kullanacağınız uçlar (kapsamlar, aşağıda);
web sitesi ya da uygulamanın kökeni (tarayıcıdan karo için, ör. https://ornek.com);
beklediğiniz kabaca istek sayısı.

Anahtar upd_ ile başlayan 47 karakterlik bir dizidir ve size bir kez gösterilir; Updraft yalnız özetini saklar. Kaybolursa yenisi açılır, eskisi iptal edilir.

Kapsamlar

Bir anahtar birden çok kapsam taşıyabilir. Gerektiğinden fazlasını istemeyin; okuma ve yazma anahtarlarını ayrı tutun.

Kapsam	Uçlar
`tiles`	Anahtarlı karo yolu, GET /v1/packs/{region}
`sites:read`	GET /v1/sites, GET /v1/regions, GET /v1/regions/{region}/profile
`flights:write`	POST /v1/flights (sunucudan sunucuya IGC yükleme)
`consents:write`	POST /v1/consents/withdrawals, POST /v1/consents/grants
`flights:share`	POST /v1/flights/{flight_id}/shares, DELETE /v1/flights/{flight_id}/shares
`replay:read`	GET /v1/replay/{public_id} (yalnız Updraft Atlas sunucusu)

GET /v1/health ve bölge paketlerinin süreli indirme adresleri anahtar istemez.

Kimlik hataları

HTTP	`code`	Ne yapmalı
401	`auth_missing`	`X-Api-Key` başlığını ekleyin
401	`auth_invalid`	Anahtar bilinmiyor: yazımı ve ortamı denetleyin
401	`auth_revoked`	Anahtar iptal edilmiş: yenisini isteyin
403	`auth_scope`	Anahtarda bu ucun kapsamı yok: kapsam isteyin

401 yanıtı WWW-Authenticate: ApiKey başlığı taşır. Bu hatalarda aynı isteği yinelemek işe yaramaz. Kimlik, dosya ve alan doğrulamasından önce denetlenir; 401 ve 403 kullanımınıza sayılmaz. Gövde biçimi: Hatalar.

Tarayıcı ve mobil

Sunucu anahtarı (sites:read, flights:write …) yalnız sunucunuzda, ortam değişkeninde ya da sır yöneticisinde durur; tarayıcıya, mobil uygulamaya, depoya ya da günlüğe girmez.
Tarayıcı ve mobil uygulama yalnız tiles kapsamlı ayrı bir anahtar kullanır. Bu anahtar istemciden çıkarılabilir; sızarsa yalnız karo okunur, yönetici iptal eder ve size yenisini verir. İptal karo sunucusunda en geç 30 saniyede geçerli olur.
Anahtarı başlıkta gönderin (MapLibre transformRequest, flutter_map TileLayer başlıkları, maplibre_gl setCustomHeaders). ?key= sorgusu da kabul edilir ama vekil ve CDN günlüklerine düşer.

İstemci paketleri

Başlığı, adresleri ve hata gövdesini sizin yerinize işleyen iki ince paket vardır; sürümleri API sürümüyle aynıdır:

Paket	Kurulum	İçerik
`@updraft/maps` (TypeScript/JavaScript)	`npm install @updraft/maps`	`UpdraftClient` (her `/v1` ucu, OpenAPI'den üretilmiş tipler), `UpdraftApiError` (`code`, `detail`, `retryAfter`, `retryable`), karo ve stil adresleri; `@updraft/maps/maplibre` MapLibre GL JS yardımcıları
`updraft_maps` (Dart/Flutter)	`flutter pub add updraft_maps`	`UpdraftClient`, `UpdraftApiException`, karo adresleri; `flutter_map.dart` ve `maplibre_gl.dart` yardımcıları

import { UpdraftApiError, UpdraftClient } from '@updraft/maps';

const client = new UpdraftClient({ apiKey: process.env.UPDRAFT_API_KEY }); // yalnız sunucuda
try {
  const page = await client.sites({ bbox: '28.5,36.0,30.0,37.2', kind: 'takeoff' });
} catch (error) {
  if (error instanceof UpdraftApiError && error.code === 'auth_scope') {
    // anahtara sites:read kapsamı eklenmeli
  }
}

Rota önerisi (GET /v1/routes) yalnız uçuş öncesi planlama içindir: seçenekleri her gösterdiğinizde, seçenek olmasa da, yanıttaki sabit uyarıyı da gösterin (preflightNotice(yanıt, 'tr')).