Herkese Açık API

openOMSI üzerinde çalışan harita, otobüs, araç, mod, nesne, eklenti ve yardımcı yazılımların topluluk uyumluluk raporlarına yapılandırılmış, salt okunur erişim. openOMSI geliştiricileri, analiz araçları, botlar ve entegrasyonlar için hazırlanmıştır.

Bu, openOMSI hatalarını bildirmek için bir API DEĞİLDİR. Motorun kendi hataları projenin resmi kanallarına aittir. Burada yalnızca topluluğun test ettiklerini okursun.

⚠ HERKESE AÇIK API İSTEK SINIRI

IP başına 60 dakikada 6 istek

Bu API herkese açık olduğu ve kimlik doğrulama gerektirmediği için kasıtlı olarak sıkı bir istek sınırı uygular.

Entegrasyonlarını yanıtları yerel olarak önbelleğe alacak şekilde tasarla.
API'yi sürekli sorgulama.
Mümkün olduğunca toplu (aggregate) uç noktaları kullanın: tek bir çağrı çoğu soruyu yanıtlar.

Sınır tüm herkese açık uç noktalar arasında paylaşılır ve yalnızca dış tüketicilere uygulanır; web sitesinin kendisi bu kotayı kullanmaz.

Hızlı başlangıç

Temel URL: https://openomsi.omsimods.com.br/api/public/v1. Her şey JSON'dur, yalnızca GET, kimlik doğrulama yok. Filtrelerin kabul ettiği tam değerleri öğrenmek için meta uç noktasıyla başla.

curl https://openomsi.omsimods.com.br/api/public/v1/meta
curl "https://openomsi.omsimods.com.br/api/public/v1/content?q=millennium&type=VEHICLE"

OpenAPI (JSON)

İstek sınırı, başlıklar ve hatalar

Her yanıt RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset başlıklarını içerir. Sınır aşıldıktan sonra API, Retry-After (saniye) ile 429 döndürür.
Koşullu istekler (If-None-Match / If-Modified-Since) gövdesiz 304 döndürür, ancak 304 de kotadan sayılır.
Hatalar her zaman aynı biçimi kullanır: {"error": code, "message": text}; durumlar 400, 404, 429 ve 500. Hiçbir zaman yığın izi (stack trace) döndürülmez.

HTTP/1.1 429 Too Many Requests
Retry-After: 1234
RateLimit-Limit: 6
RateLimit-Remaining: 0
RateLimit-Reset: 1234

{
  "error": "rate_limit_exceeded",
  "message": "Public API limit reached. Try again later.",
  "retry_after": 1234
}

Pratik kullanım senaryoları

Örnek değerler açıklayıcıdır; yanıtların yapısı gerçektir.

1. Grand Paris Moulon Windows'ta çalışıyor mu?

Tek bir çağrı platform bazında özeti, sorun kategorilerini, FPS dağılımını, test edilen sürümleri ve en son raporları döndürür. compatibility.by_platform.WINDOWS alanını oku.

GET https://openomsi.omsimods.com.br/api/public/v1/content/grand-paris-moulon

Yanıt (kısaltılmış)

{
  "compatibility": {
    "total_reports": 4,
    "works": 2,
    "works_with_issues": 2,
    "does_not_work": 0,
    "inconclusive": 0,
    "low_data": false,
    "by_platform": {
      "WINDOWS": {
        "reports": 4,
        "works": 2,
        "works_with_issues": 2,
        "does_not_work": 0,
        "inconclusive": 0,
        "latest_tested_openomsi_version": "0.1.126",
        "fps": {
          "samples": 3,
          "median": 38,
          "min": 28,
          "max": 60
        }
      }
    }
  },
  "issues": {
    "by_category": {
      "TEXTURES": 2,
      "SCRIPTS": 1
    },
    "reports_with_issues": 2
  },
  "performance": {
    "source": "user_reported",
    "fps": {
      "samples": 3,
      "median": 38,
      "min": 28,
      "max": 60
    },
    "load_time_seconds": {
      "samples": 2,
      "median": 95,
      "min": 80,
      "max": 110
    }
  },
  "latest_tested_openomsi_version": "0.1.126"
}

2. Android'de test edilen haritaları listeleme

Tür ve platforma göre filtrele. Her öğe toplamları, test edilen platformları ve test edilen en son openOMSI sürümünü zaten içerir.

GET https://openomsi.omsimods.com.br/api/public/v1/content?type=MAP&platform=ANDROID&sort=reports&limit=20

Yanıt (kısaltılmış)

{
  "data": [
    {
      "id": "cm0millennium1",
      "slug": "mapa-brigadeiro-sampaio",
      "name": "Mapa Brigadeiro Sampaio",
      "type": "MAP",
      "author": null,
      "current_version": null,
      "url": "https://openomsi.omsimods.com.br/conteudo/caio-millennium-brt-i-o500u",
      "source_url": "https://omsimods.com.br/",
      "image_url": null,
      "omsimodsbr_verified": true,
      "reports": {
        "total": 3,
        "works": 0,
        "works_with_issues": 3,
        "does_not_work": 0,
        "inconclusive": 0,
        "by_platform": {
          "WINDOWS": {
            "reports": 3,
            "works": 0,
            "works_with_issues": 3,
            "does_not_work": 0,
            "inconclusive": 0
          }
        }
      },
      "reports_with_issues": 3,
      "latest_tested_openomsi_version": "0.1.126",
      "latest_test_at": "2026-09-29T15:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

3. Bir openOMSI geliştiricisi olarak mevcut sürümdeki doku sorunlarını gösterme

Raporları openOMSI sürümüne ve sorun kategorisine göre filtrele. Her rapor, yapılandırılmış issue_categories alanını ve test edenin açıklamasını listeler.

GET https://openomsi.omsimods.com.br/api/public/v1/reports?openomsi_version=0.1.126&issue_category=TEXTURES&limit=50

Yanıt (kısaltılmış)

{
  "data": [
    {
      "id": "cm0report0001",
      "content": {
        "id": "cm0grandparis01",
        "slug": "grand-paris-moulon",
        "name": "Grand Paris Moulon",
        "type": "MAP"
      },
      "content_version": null,
      "openomsi_version": "0.1.126",
      "platform": "WINDOWS",
      "architecture": "X64",
      "result": "WORKS_WITH_ISSUES",
      "fps": {
        "avg": 41,
        "min": 28,
        "max": 60
      },
      "load_time_seconds": 95,
      "device": {
        "label": "Desktop GTX 1060",
        "model": null,
        "os_version": "Windows 11",
        "cpu": "Ryzen 5 3600",
        "gpu": "GTX 1060 6GB",
        "ram_gb": 16
      },
      "issue_categories": [
        "TEXTURES"
      ],
      "issue_description": "Windows of some black buses render with wrong textures.",
      "notes": null,
      "tested_at": "2026-09-29T17:02:00.000Z",
      "screenshot_url": null,
      "author": {
        "display_name": "tester"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

4. Sürümler arasında olası bir gerilemeyi tespit etme

compare bir içeriği iki sürümde yan yana gösterir; regressions daha önce çalışıp şimdi sorun bildirilen tüm içerikleri listeler. Sonuçlar yalnızca olası gerilemelerdir, hiçbir zaman doğrulanmış değildir.

GET https://openomsi.omsimods.com.br/api/public/v1/compatibility/compare?content=grand-paris-moulon&from=0.1.121&to=0.1.126
GET https://openomsi.omsimods.com.br/api/public/v1/compatibility/regressions?from=0.1.121&to=0.1.126&type=BUS

Yanıt (kısaltılmış)

{
  "changes": [
    {
      "platform": "WINDOWS",
      "from": {
        "works": 3,
        "works_with_issues": 0,
        "does_not_work": 0,
        "inconclusive": 0
      },
      "to": {
        "works": 1,
        "works_with_issues": 3,
        "does_not_work": 0,
        "inconclusive": 0
      },
      "from_reports": 3,
      "to_reports": 4,
      "possible_regression": true
    }
  ],
  "possible_regression": true
}

5. Bir Discord botunu besleme

Ada göre ara, ardından yanıtı ilk öğeden oluştur: ad, platform, sonuç, test edilen en son sürüm ve rapor sayısı. Kendi tarafında önbelleğe al.

GET https://openomsi.omsimods.com.br/api/public/v1/content?q=grand%20paris&platform=WINDOWS&limit=1

Yanıt (kısaltılmış)

{
  "data": [
    {
      "name": "Grand Paris Moulon",
      "reports": {
        "total": 4,
        "works": 2,
        "works_with_issues": 2
      },
      "latest_tested_openomsi_version": "0.1.126"
    }
  ]
}

Önerilen bot yanıtı

Grand Paris Moulon
Windows
⚠ Sorunlu çalışıyor
Son test edilen: 0.1.126
Raporlar: 4

6. Android'de en çok hangi sorunlar bildiriliyor?

issues uç noktası kategorileri rapor sayısı ve farklı içerik sayısıyla toplar; platform uç noktası en çok bildirilen cihazları ve FPS'i ekler.

GET https://openomsi.omsimods.com.br/api/public/v1/issues?platform=ANDROID&openomsi_version=0.1.126
GET https://openomsi.omsimods.com.br/api/public/v1/platforms/android

Yanıt (kısaltılmış)

{
  "data": [
    {
      "category": "TEXTURES",
      "reports": 31,
      "contents": 18
    },
    {
      "category": "PHYSICS",
      "reports": 22,
      "contents": 14
    }
  ]
}

7. Güncel sürüm ve indirmeler

releases/latest sürümü, yayın tarihini, GitHub URL'sini ve platform ile mimariye göre resmi indirme dosyalarını döndürür.

GET https://openomsi.omsimods.com.br/api/public/v1/releases/latest

Yanıt (kısaltılmış)

{
  "version": "0.1.126",
  "published_at": "2026-09-27T20:11:00.000Z",
  "github_url": "https://github.com/openOMSI-org/openOMSI/releases/tag/v0.1.126",
  "assets": [
    {
      "key": "android-arm64",
      "label": "Android ARM64",
      "platform": "ANDROID",
      "architecture": "ARM64",
      "type": "CLIENT",
      "name": "openOMSI-android-arm64.apk",
      "download_url": "https://github.com/openOMSI-org/openOMSI/releases/download/v0.1.126/openOMSI-android-arm64.apk",
      "size_bytes": 152043520
    }
  ]
}

8. Henüz kimsenin test etmediği içerikleri bulma

has_reports=false, raporu olmayan onaylı içerikleri listeler; type veya q ile birleştir.

GET https://openomsi.omsimods.com.br/api/public/v1/content?has_reports=false&type=MAP&limit=50

Yanıt (kısaltılmış)

{
  "data": [
    {
      "name": "…",
      "type": "MAP",
      "reports": {
        "total": 0
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 312,
    "pages": 7
  }
}

Uç noktalar

Tüm yollar https://openomsi.omsimods.com.br/api/public/v1 ile başlar. Makine tarafından okunabilir tam açıklama OpenAPI belgesidir.

Uç nokta	Ne döndürür
`GET /meta`	Taksonomiler, sınırlar ve API sürümü.
`GET /status`	Çalışma denetimi (bu da istek sınırına tabidir: sürekli sorgulama).
`GET /content`	Rapor toplamları, test edilen platformlar ve öğe başına test edilen en son sürümle içerik araması.
`GET /content/{slug}`	Tek çağrıda bir içerik: kaynaklar, uyumluluk, sorunlar, performans, test edilen sürümler, cihazlar ve en son raporlar.
`GET /reports`	Yapılandırılmış sorun kategorileri, FPS, donanım ve tarihlerle tekil raporlar.
`GET /compatibility`	openOMSI sürümüne, platforma veya içerik türüne göre toplu veri.
`GET /compatibility/compare`	Bir içeriğin iki openOMSI sürümü arasında karşılaştırılması.
`GET /compatibility/regressions`	Ardışık test edilen sürümler arasındaki olası gerilemeler.
`GET /issues`	Rapor sayısına ve etkilenen içeriklere göre sıralanmış sorun kategorileri.
`GET /platforms/{platform}`	Tek bir platform için toplu veri (android, windows, linux, macos).
`GET /devices`	Test edenlerin girdiği donanımlar, gruplanmış ve sayılmış.
`GET /runtime-reports`	openOMSI'nin kendisinin cihaz testleri (oturum hiç başlamamış olabilir): donanım, işletim sistemi, ne kadar ilerlediği, grafik API'si, sanitize edilmiş hata metni ve isteğe bağlı sanitize edilmiş günlük. İçerik söz konusu değildir.
`GET /runtime-reports/{id}`	Tek bir cihaz testi; varsa sanitize edilmiş günlüğüyle birlikte.
`GET /releases/latest`	Güncel sürüm ve resmi indirme dosyaları.
`GET /releases`	Sayfalanmış sürüm geçmişi.

Cihaz testleri hiçbir zaman özgün günlüğü, IP adreslerini, e-postaları, kullanıcı adlarını veya hesap tanımlayıcılarını göstermez: yalnızca teknik veriler ve sanitize edilmiş günlük. Bunlar topluluk gözlemleridir; kıyaslama (benchmark) ya da resmi bir gereksinim değildir.

Filtreler, sayfalama, sıralama ve alanlar

Sayfalama: page (1'den başlar) ve limit (varsayılan 20, en fazla 50). Listeler {"data": [...], "pagination": {page, limit, total, pages}} biçiminde yanıt verir.
Sıralama: sort = reports, recent, name, latest_test veya issues; order = asc veya desc.
İsteğe bağlı fields=name,slug,type, her öğenin yalnızca bu üst düzey alanlarını tutar. Varsayılan yanıt zaten eksiksizdir.
Enum filtreleri büyük/küçük harfe duyarsızdır ve virgülle ayrılmış listeleri kabul eder (platform=ANDROID,WINDOWS).
İçerik aramasında rapor filtreleri (platform, result, openomsi_version, issue_category) kullanıldığında, sayılar eşleşen raporlara aittir.

Parametreler

Parametre	Açıklama
`q`	İçerik adları ve takma adlarında metin araması.
`type`	İçerik türü. Virgülle ayrılmış liste kullanılabilir.
`platform`	Raporun platformu. Virgülle ayrılmış liste kullanılabilir.
`result`	Test eden kişinin bildirdiği sonuç. Virgülle ayrılmış liste kullanılabilir.
`openomsi_version`	Testin çalıştırıldığı openOMSI sürümü.
`issue_category`	Rapora eklenen sorun kategorisi (AUDIO, SOUND için takma ad olarak kabul edilir). Virgülle ayrılmış liste kullanılabilir.
`author`	İçerik yazarı (kısmi eşleşme).
`has_reports`	true: yalnızca test edilmiş içerikler; false: henüz kimsenin test etmediği içerikler.
`sort`	Sıralama alanı.
`order`	Sıralama yönü.
`page`	Sayfa numarası, 1'den başlar.
`limit`	Sayfa başına öğe sayısı (en fazla 50).
`fields`	Her öğede tutulacak, virgülle ayrılmış üst düzey alanlar (isteğe bağlı; varsayılan olarak öğenin tamamı döner).
`content`	İçerik slug'ı veya kimliği (tam eşleşme) ya da adının bir kısmı.
`architecture`	Raporun CPU mimarisi. Virgülle ayrılmış liste kullanılabilir.
`device`	Cihaz adında geçen metin.
`has_fps`	Yalnızca FPS değeri olan (true) veya olmayan (false) raporlar.
`from`	reports: bu ISO tarihinde veya sonrasında test edilenler. compare/regressions: eski openOMSI sürümü.
`to`	reports: bu ISO tarihinde veya öncesinde test edilenler. compare/regressions: yeni openOMSI sürümü.
`startup_stage`	openOMSI'nin cihazda ne kadar ilerlediği. Virgülle ayrılmış liste kullanılabilir.
`graphics_backend`	Testi yapan kişinin seçtiği grafik API'si. Virgülle ayrılmış liste kullanılabilir.
`gpu`	GPU adında geçen metin.
`cpu`	CPU adında geçen metin.
`manufacturer`	Cihaz üreticisi (kısmi eşleşme).
`device_model`	Cihaz modeli (kısmi eşleşme).
`os_version`	İşletim sistemi sürümü (kısmi eşleşme).
`media_indexing_observed`	Android: test eden kişi, galerinin veya medya tarayıcısının OMSI görsellerini indekslediğini (true) ya da indekslemediğini (false) bildirdi.
`has_log`	Yalnızca sanitize edilmiş günlüğü olan (true) veya olmayan (false) testler.
`include_log`	Her öğeye sanitized_log alanını ekler (varsayılan false: liste yalnızca has_sanitized_log bilgisini verir).

Enum'lar / Taksonomiler

Uygulamanın kendi listelerinden üretilmiştir. AUDIO, filtrelerde SOUND için takma ad olarak kabul edilir.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Performans verileri

FPS ve yükleme süreleri KULLANICI TARAFINDAN BİLDİRİLEN verilerdir, kontrollü bir kıyaslama (benchmark) değildir. İstatistikler önce medyanı kullanır ve her zaman örnek sayısını (samples) ile en düşük ve en yüksek değeri içerir.

Önbellek, CORS ve sürümleme

Yanıtlar Cache-Control, ETag ve Last-Modified içerir. Tarayıcılar bunları birkaç dakika yeniden kullanabilir; paylaşımlı önbellekler, kotanın her zaman uygulanması için yeniden doğrulama yapmalıdır.
CORS yalnızca GET, HEAD ve OPTIONS için açıktır. Yazma yöntemleri yoktur.
API, yolda sürümlenir (/api/public/v1). Eski sürümsüz yollar v1'e yönlendirilir (308). Geriye dönük uyumsuz değişiklikler yalnızca yeni bir sürüm olarak yayımlanır.
openOMSI Compatibility web sitesi kendi veritabanını doğrudan okur ve bu API'yi ya da kotasını hiçbir zaman kullanmaz.

Entegrasyon yönergeleri

Verileri yerel olarak önbelleğe al.
Sürekli sorgulamaktan kaçın; yalnızca gerektiğinde istek yap.
Toplu uç noktaları kullan (content detail, compatibility, issues, platforms).
Retry-After ve RateLimit-* başlıklarına uy.
API eşdeğer veri sunuyorsa HTML'i kazıma (scraping).
Topluluk raporlarından doğrulanmış motor hataları çıkarma.
Analizlerinde her zaman openOMSI sürümünü belirt.

Veriler hakkında

Topluluk raporları gözlemlerdir, yetkili birer uyumluluk sertifikası değildir. Tek bir rapor ne "bu mod uyumludur" ne de "bu bir openOMSI hatasıdır" anlamına gelir. Örnek sayısını, openOMSI sürümünü, platformu, donanımı, içerik sürümünü, sorun kategorisini ve raporlar arasındaki tutarlılığı dikkate al.

Gizlilik

Yanıtlar hiçbir zaman Discord kimlikleri, e-posta adresleri, IP adresleri, oturumlar, bildirim abonelikleri, moderasyon verileri veya cihaz tanımlayıcıları içermez. Raporlar yalnızca herkese açık görünen adı ve test edenin yayımlamayı seçtiği donanımı gösterir. Bir raporda issue_categories yapılandırılmıştır; issue_description ise test edenin tüm rapor için yazdığı tek serbest metin açıklamadır.

https://openomsi.omsimods.com.br/api/openapi.json