Nyilvános API

Strukturált, csak olvasható hozzáférés az openOMSI-n futó térképek, buszok, járművek, modok, objektumok, pluginok és segédprogramok közösségi kompatibilitási jelentéseihez. openOMSI-fejlesztőknek, elemzőeszközöknek, botoknak és integrációknak készült.

Ez NEM az openOMSI hibáinak bejelentésére szolgáló API. A motor saját hibái a projekt hivatalos csatornáira tartoznak. Itt csak azt olvashatod, amit a közösség kipróbált.

⚠ NYILVÁNOS API KÉRÉSKORLÁT

6 kérés IP-címenként 60 percen belül

Ez az API szándékosan szigorú kéréskorlátot alkalmaz, mert nyilvános, és nem igényel hitelesítést.

Úgy tervezd az integrációkat, hogy a válaszokat helyben gyorsítótárazzák.
Ne kérdezd le folyamatosan az API-t.
Amikor csak lehet, használj összesítő végpontokat: egy hívás a legtöbb kérdésre választ ad.

A korlát minden nyilvános végpontra közös, és csak külső felhasználókra vonatkozik; maga a weboldal nem használja ezt a keretet.

Gyorsindítás

Alap URL: https://openomsi.omsimods.com.br/api/public/v1. Minden válasz JSON, csak GET kérések, hitelesítés nélkül. Kezdd a meta végponttal, hogy megtudd a szűrők által elfogadott pontos értékeket.

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)

Kéréskorlát, fejlécek és hibák

Minden válasz tartalmazza a RateLimit-Limit, RateLimit-Remaining és RateLimit-Reset fejlécet. A korlát elérése után az API 429-cel válaszol Retry-After fejléccel (másodpercben).
A feltételes kérések (If-None-Match / If-Modified-Since) törzs nélküli 304-et adnak vissza, de a 304 is beleszámít a keretbe.
A hibák mindig ugyanazt a formátumot használják: {"error": code, "message": text}; státuszok: 400, 404, 429 és 500. Veremnyomot (stack trace) soha nem adunk vissza.

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
}

Gyakorlati felhasználási esetek

A példaértékek szemléltető jellegűek; a válaszok szerkezete valódi.

1. Működik a Grand Paris Moulon Windowson?

Egyetlen hívás visszaadja a platformonkénti összegzést, a hibakategóriákat, az FPS-eloszlást, a tesztelt verziókat és a legutóbbi jelentéseket. Olvasd a compatibility.by_platform.WINDOWS mezőt.

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

Válasz (rövidítve)

{
  "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. Androidon tesztelt térképek listázása

Szűrj típus és platform szerint. Minden elem már tartalmazza az összesítéseket, a tesztelt platformokat és a legutóbb tesztelt openOMSI-verziót.

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

Válasz (rövidítve)

{
  "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. openOMSI-fejlesztőként textúrahibák megjelenítése az aktuális verzióban

Szűrd a jelentéseket openOMSI-verzió és hibakategória szerint. Minden jelentés felsorolja a strukturált issue_categories mezőt és a tesztelő leírását.

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

Válasz (rövidítve)

{
  "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. Lehetséges regresszió felismerése verziók között

A compare egy tartalmat mutat egymás mellett két verzióban; a regressions felsorol minden olyan tartalmat, amely korábban működött, de most hibát jelentenek róla. Az eredmények csak lehetséges regressziók, soha nem megerősítettek.

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

Válasz (rövidítve)

{
  "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. Discord bot kiszolgálása

Keress név alapján, majd az első elemből építsd fel a választ: név, platform, eredmény, legutóbb tesztelt verzió és a jelentések száma. Gyorsítótárazd a saját oldaladon.

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

Válasz (rövidítve)

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

Javasolt botválasz

Grand Paris Moulon
Windows
⚠ Hibákkal működik
Legutóbb tesztelve: 0.1.126
Jelentések: 4

6. Mely hibákat jelentik a legtöbbször Androidon?

Az issues végpont a kategóriákat a jelentések és a különböző tartalmak számával összesíti; a platform végpont hozzáadja a legtöbbet jelentett eszközöket és az FPS-t.

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

Válasz (rövidítve)

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

7. Aktuális kiadás és letöltések

A releases/latest visszaadja a verziót, a megjelenés dátumát, a GitHub URL-t és a hivatalos letöltési fájlokat platform és architektúra szerint.

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

Válasz (rövidítve)

{
  "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. Olyan tartalmak keresése, amelyeket még senki sem tesztelt

A has_reports=false a jelentés nélküli, jóváhagyott tartalmakat listázza; kombináld a type vagy q paraméterrel.

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

Válasz (rövidítve)

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

Végpontok

Minden útvonal https://openomsi.omsimods.com.br/api/public/v1 előtaggal kezdődik. A teljes, géppel olvasható leírás az OpenAPI-dokumentum.

Végpont	Mit ad vissza
`GET /meta`	Taxonómiák, korlátok és API-verzió.
`GET /status`	Működésellenőrzés (ez is kéréskorlátos: ne kérdezd le folyamatosan).
`GET /content`	Tartalomkeresés jelentésösszesítésekkel, tesztelt platformokkal és elemenként a legutóbb tesztelt verzióval.
`GET /content/{slug}`	Egy tartalom egyetlen hívásban: források, kompatibilitás, hibák, teljesítmény, tesztelt verziók, eszközök és legutóbbi jelentések.
`GET /reports`	Egyedi jelentések strukturált hibakategóriákkal, FPS-sel, hardverrel és dátumokkal.
`GET /compatibility`	Összesítés openOMSI-verzió, platform vagy tartalomtípus szerint.
`GET /compatibility/compare`	Egy tartalom összehasonlítása két openOMSI-verzió között.
`GET /compatibility/regressions`	Lehetséges regressziók egymást követő tesztelt verziók között.
`GET /issues`	Hibakategóriák a jelentések és az érintett tartalmak száma szerint rangsorolva.
`GET /platforms/{platform}`	Egy platform összesítése (android, windows, linux, macos).
`GET /devices`	A tesztelők által megadott hardverek, csoportosítva és megszámolva.
`GET /runtime-reports`	Az openOMSI saját eszköztesztjei (előfordulhat, hogy a munkamenet el sem indult): hardver, operációs rendszer, meddig jutott, grafikus API, megtisztított hibaszöveg és opcionális megtisztított napló. Tartalom nem kapcsolódik hozzájuk.
`GET /runtime-reports/{id}`	Egy eszköztesztje, a megtisztított naplójával, ha van.
`GET /releases/latest`	Aktuális kiadás és hivatalos letöltési fájlok.
`GET /releases`	Lapozható kiadástörténet.

Az eszköztesztek soha nem teszik elérhetővé az eredeti naplót, az IP-címeket, az e-mail-címeket, a felhasználóneveket és a fiókazonosítókat: csak műszaki adatokat és a megtisztított naplót tartalmaznak. Közösségi megfigyelések, nem benchmark és nem hivatalos követelmény.

Szűrők, lapozás, rendezés és mezők

Lapozás: page (1-től) és limit (alapértelmezés 20, maximum 50). A listák válasza {"data": [...], "pagination": {page, limit, total, pages}}.
Rendezés: sort = reports, recent, name, latest_test vagy issues; order = asc vagy desc.
Az opcionális fields=name,slug,type csak ezeket a legfelső szintű mezőket tartja meg minden elemből. Az alapértelmezett válasz már teljes.
Az enum szűrők nem különböztetik meg a kis- és nagybetűket, és vesszővel elválasztott listákat fogadnak el (platform=ANDROID,WINDOWS).
Ha a tartalomkeresésben jelentésszűrőket (platform, result, openomsi_version, issue_category) használsz, a számok a megfelelő jelentésekre vonatkoznak.

Paraméterek

Paraméter	Leírás
`q`	Szöveges keresés a tartalmak nevében és alternatív neveiben.
`type`	Tartalom típusa. Vesszővel elválasztott lista megengedett.
`platform`	A jelentés platformja. Vesszővel elválasztott lista megengedett.
`result`	A tesztelő által jelentett eredmény. Vesszővel elválasztott lista megengedett.
`openomsi_version`	Az openOMSI verziója, amelyen a teszt futott.
`issue_category`	A jelentéshez csatolt hibakategória (az AUDIO a SOUND aliasaként is elfogadott). Vesszővel elválasztott lista megengedett.
`author`	A tartalom szerzője (részleges egyezés).
`has_reports`	true: csak tesztelt tartalmak; false: csak olyan tartalmak, amelyeket még senki sem tesztelt.
`sort`	Rendezési mező.
`order`	Rendezési irány.
`page`	Oldalszám, 1-től kezdődően.
`limit`	Elemek száma oldalanként (legfeljebb 50).
`fields`	Vesszővel elválasztott legfelső szintű mezők, amelyek megmaradnak minden elemben (opcionális; alapértelmezés szerint a teljes elem).
`content`	A tartalom slugja vagy azonosítója (pontos egyezés), vagy a nevének egy része.
`architecture`	A jelentés CPU-architektúrája. Vesszővel elválasztott lista megengedett.
`device`	Az eszköz nevében szereplő szöveg.
`has_fps`	Csak azok a jelentések, amelyekben van (true) vagy nincs (false) FPS-érték.
`from`	reports: ezen az ISO-dátumon vagy később tesztelve. compare/regressions: régebbi openOMSI-verzió.
`to`	reports: ezen az ISO-dátumon vagy korábban tesztelve. compare/regressions: újabb openOMSI-verzió.
`startup_stage`	Meddig jutott az openOMSI az eszközön. Vesszővel elválasztott lista megengedett.
`graphics_backend`	A tesztelő által választott grafikus API. Vesszővel elválasztott lista megengedett.
`gpu`	A GPU nevében szereplő szöveg.
`cpu`	A CPU nevében szereplő szöveg.
`manufacturer`	Az eszköz gyártója (részleges egyezés).
`device_model`	Az eszköz modellje (részleges egyezés).
`os_version`	Az operációs rendszer verziója (részleges egyezés).
`media_indexing_observed`	Android: a tesztelő jelezte, hogy a galéria vagy a médiaszkenner indexelte az OMSI képeit (true), vagy nem (false).
`has_log`	Csak megtisztított naplóval (true) vagy anélkül (false) rendelkező tesztek.
`include_log`	A sanitized_log mezőt minden elembe belefoglalja (alapértelmezés false: a lista csak a has_sanitized_log értéket adja meg).

Enumok / Taxonómiák

Az alkalmazás saját listáiból generálva. Az AUDIO a szűrőkben a SOUND aliasaként is elfogadott.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Teljesítményadatok

Az FPS- és betöltési idők FELHASZNÁLÓK ÁLTAL JELENTETT adatok, nem ellenőrzött benchmarkok. A statisztikák elsősorban a mediánt használják, és mindig tartalmazzák a mintaméretet (samples), valamint a minimumot és a maximumot.

Gyorsítótár, CORS és verziókezelés

A válaszok tartalmazzák a Cache-Control, ETag és Last-Modified fejlécet. A böngészők pár percig újra felhasználhatják őket; a megosztott gyorsítótáraknak újra kell validálniuk a választ, hogy a keret mindig érvényesüljön.
A CORS csak a GET, HEAD és OPTIONS metódusokra nyitott. Írási metódusok nincsenek.
Az API verziója az útvonalban szerepel (/api/public/v1). A régebbi, verzió nélküli útvonalak átirányítanak (308) a v1-re. Visszafelé nem kompatibilis változtatások csak új verzióként jelennek meg.
Az openOMSI Compatibility weboldal közvetlenül a saját adatbázisát olvassa, és soha nem használja ezt az API-t vagy annak keretét.

Integrációs irányelvek

Gyorsítótárazd az adatokat helyben.
Kerüld a folyamatos lekérdezést; csak szükség esetén kérj.
Használj összesítő végpontokat (content detail, compatibility, issues, platforms).
Tartsd tiszteletben a Retry-After és a RateLimit-* fejléceket.
Ne a HTML-ből nyerd ki az adatokat (scraping), ha az API ugyanazt megadja.
Ne következtess megerősített motorhibákra közösségi jelentésekből.
Az elemzéseidben mindig tüntesd fel az openOMSI verzióját.

Az adatokról

A közösségi jelentések megfigyelések, nem hivatalos kompatibilitási tanúsítványok. Egyetlen jelentés sem jelenti azt, hogy „ez a mod kompatibilis”, sem azt, hogy „ez openOMSI-hiba”. Vedd figyelembe a minták számát, az openOMSI-verziót, a platformot, a hardvert, a tartalom verzióját, a hibakategóriát és a jelentések közötti egyezést.

Adatvédelem

A válaszok soha nem tartalmaznak Discord-azonosítókat, e-mail-címeket, IP-címeket, munkameneteket, értesítési feliratkozásokat, moderációs adatokat vagy eszközazonosítókat. A jelentések csak a nyilvános megjelenített nevet és a tesztelő által közzétenni választott hardvert mutatják. Egy jelentésben az issue_categories strukturált, az issue_description pedig a tesztelő egyetlen szabad szöveges leírása az egész jelentésről.

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