REST API v1

Geliştirici API Belgeleri

Hizmy platformu, Türkiye geneli hizmet ekosistemini ve şeffaf piyasa verilerini geliştiricilere ve araştırmacılara açar. Hiçbir uç nokta telefon, e-posta veya adres vermez. Usta dizini, ustaların profilinde zaten herkese açık olan ad ve puan bilgilerini içerir; açık veri ve fiyat uçları yalnızca toplu istatistik verir.

Temel İlkeler ve Veri Gizliliği

Bu API üzerinden yalnızca kamuya açık hizmet kataloğu, il/ilçe adları, kamuya açık usta dizini, toplulaştırılmış açık pazar istatistikleri ve gerçekleşen fiyat özetleri sunulur. Müşterilerin ve ustaların telefon numaraları, e-posta adresleri, kimlik bilgileri, açık adresleri ve özel mesajları API üzerinden kesinlikle paylaşılmaz.

Kimlik Doğrulama

API istekleri için 'hz_' ile başlayan bir anahtar kullanılır. Anahtarını istek başlığında aşağıdaki iki yöntemden biriyle iletebilirsin:

1. Authorization başlığı (Önerilen)

Authorization: Bearer hz_1234567890abcdef...

2. x-api-key başlığı

x-api-key: hz_1234567890abcdef...

Oran Sınırları & Yanıt Başlıkları

API anahtarın için tanımlı dakikalık istek sınırı aşıldığında sunucu HTTP 429 Too Many Requests durum kodu ve Retry-After başlığı döndürür.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 35

{
  "error": {
    "code": "rate_limited",
    "message": "Dakikalık istek sınırı aşıldı"
  }
}

Hata Biçimi

Hata yanıtları standart JSON biçiminde döner:

{
  "error": {
    "code": "unauthorized",
    "message": "API anahtarı gerekli: Authorization: Bearer hz_..."
  }
}

Uç Noktalar

GET/api/v1/catalog

Scope: catalog

Hizmet Kataloğu

Platformda yer alan tüm aktif hizmet alanları, kategoriler ve hizmetlerin hiyerarşik listesi.

Sorgu Parametreleri

Sorgu parametresi almaz.

cURL

curl -H "Authorization: Bearer hz_9a8b7c6d5e4f3a2b1c" \
  "https://api.platform.yerel/api/v1/catalog"

JSON Response

{
  "areas": [
    {
      "slug": "tadilat",
      "name": { "tr": "Tadilat", "en": "Renovation" },
      "groups": [
        {
          "slug": "boya-badana-grubu",
          "name": { "tr": "Boya Badana", "en": "Painting" },
          "services": [
            { "slug": "boya-badana", "name": { "tr": "Boya Badana", "en": "Interior Painting" } }
          ]
        }
      ]
    }
  ]
}

GET/api/v1/locations

Scope: locations

İl ve İlçeler

Türkiye'nin 81 ili ve bağlı ilçelerinin plaka koduna göre sıralı listesi.

Sorgu Parametreleri

Sorgu parametresi almaz.

cURL

curl -H "Authorization: Bearer hz_9a8b7c6d5e4f3a2b1c" \
  "https://api.platform.yerel/api/v1/locations"

JSON Response

{
  "provinces": [
    {
      "slug": "istanbul",
      "name": "İstanbul",
      "region": "marmara",
      "districts": [
        { "slug": "kadikoy", "name": "Kadıköy" },
        { "slug": "besiktas", "name": "Beşiktaş" }
      ]
    }
  ]
}

GET/api/v1/providers

Scope: providers

Usta Dizini

Platformdaki ustalara ait herkese açık dizin bilgileri (ad, slug, değerlendirme puanı, hizmetler, il sayısı). Kişisel iletişim ve adres bilgisi içermez.

Sorgu Parametreleri

hizmet (isteğe bağlı): Hizmet slug'ına göre filtreleme (ör. boya-badana)
il (isteğe bağlı): İl slug'ına göre filtreleme (ör. istanbul)
cursor (isteğe bağlı): Sayfalama için önceki sayfanın son usta slug'ı

cURL

curl -H "x-api-key: hz_9a8b7c6d5e4f3a2b1c" \
  "https://api.platform.yerel/api/v1/providers?hizmet=boya-badana&il=istanbul"

JSON Response

{
  "items": [
    {
      "slug": "ahmet-usta-kadikoy",
      "name": "Ahmet Y.",
      "rating": 4.9,
      "ratingCount": 38,
      "services": ["Boya Badana", "Alçıpan"],
      "provinceCount": 1
    }
  ],
  "nextCursor": "ahmet-usta-kadikoy"
}

GET/api/v1/open-data

Scope: open-data

Açık Veri Anlık Görüntüsü

Son 12 ayın hizmet alanı ve coğrafi bölge bazında talep dağılımı ve saatlik yoğunluk. Gizlilik eşiği (en az 30 kayıt ve 10 farklı hesap) altındaki hücreler null döner.

Sorgu Parametreleri

Sorgu parametresi almaz.

cURL

curl -H "Authorization: Bearer hz_9a8b7c6d5e4f3a2b1c" \
  "https://api.platform.yerel/api/v1/open-data"

JSON Response

{
  "license": "CC BY 4.0",
  "generatedAt": "2026-11-01T12:00:00Z",
  "months": ["2026-09", "2026-10", "2026-11"],
  "byAreaMonth": [
    { "areaSlug": "tadilat", "counts": [142, 185, 210] }
  ],
  "byRegion": [
    { "region": "marmara", "count": 1250 }
  ]
}

GET/api/v1/prices/{hizmet}/{il}

Scope: prices

Gerçekleşen Fiyat İstatistikleri

Son 24 ayda iki tarafça onaylanmış mutabakatlardan derlenen anonim fiyat dağılımı. Örneklem eşik altındaysa özet null döner.

Yol Parametreleri

hizmet (zorunlu): Hizmet slug'ı (ör. boya-badana)
il (zorunlu): İl slug'ı (ör. istanbul)

cURL

curl -H "Authorization: Bearer hz_9a8b7c6d5e4f3a2b1c" \
  "https://api.platform.yerel/api/v1/prices/boya-badana/istanbul"

JSON Response

{
  "service": { "slug": "boya-badana", "name": { "tr": "Boya Badana" } },
  "province": { "slug": "istanbul", "name": "İstanbul" },
  "summary": {
    "count": 64,
    "medianKurus": 750000,
    "meanKurus": 782000,
    "p25Kurus": 550000,
    "p75Kurus": 950000
  },
  "updatedAt": "2026-10-28T14:30:00Z"
}

Açık Veri Lisansı (CC BY 4.0)

Açık veri uç noktalarından elde edilen veriler Creative Commons Attribution 4.0 International (CC BY 4.0) lisansı altındadır. Veriyi ticari ve ticari olmayan amaçlarla kullanabilir, paylaşabilir ve uyarlayabilirsin; tek şart platformu kaynak olarak belirtmektir.

API ve açık veri kullanım koşulları

Creative Commons BY 4.0

API Anahtarı Talebi

Entegrasyon ya da araştırma amacıyla API anahtarı edinmek için kurumsal başvuru formunu doldurabilirsin.

Kurumsal başvuru formu