Publiczne API

Ustrukturyzowany dostęp tylko do odczytu do raportów zgodności od społeczności dla map, autobusów, pojazdów, modów, obiektów, wtyczek i narzędzi działających w openOMSI. Stworzone dla deweloperów openOMSI, narzędzi analitycznych, botów i integracji.

To NIE jest API do zgłaszania błędów openOMSI. Błędy samego silnika należy zgłaszać oficjalnymi kanałami projektu. Tutaj można jedynie odczytać, co przetestowała społeczność.

⚠ LIMIT ZAPYTAŃ PUBLICZNEGO API

6 zapytań na IP na 60 minut

To API ma celowo bardzo restrykcyjny limit zapytań, ponieważ jest publiczne i nie wymaga uwierzytelniania.

Projektuj integracje tak, aby lokalnie buforowały odpowiedzi.
Nie odpytuj API w sposób ciągły.
Wszędzie, gdzie to możliwe, używaj endpointów zbiorczych: jedno wywołanie odpowiada na większość pytań.

Limit jest wspólny dla wszystkich publicznych endpointów i dotyczy wyłącznie zewnętrznych odbiorców; sama strona internetowa nie korzysta z tej puli.

Szybki start

Bazowy URL: https://openomsi.omsimods.com.br/api/public/v1. Wszystko to JSON, tylko GET, bez uwierzytelniania. Zacznij od endpointu meta, aby poznać dokładne wartości akceptowane przez filtry.

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)

Limit zapytań, nagłówki i błędy

Każda odpowiedź zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset. Po przekroczeniu limitu API odpowiada 429 z Retry-After (w sekundach).
Zapytania warunkowe (If-None-Match / If-Modified-Since) zwracają 304 bez treści, ale 304 nadal wlicza się do limitu.
Błędy zawsze mają ten sam format {"error": code, "message": text}; statusy 400, 404, 429 i 500. Ślady stosu nigdy nie są zwracane.

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
}

Praktyczne przypadki użycia

Przykładowe wartości są poglądowe; struktura odpowiedzi jest prawdziwa.

1. Czy Grand Paris Moulon działa na Windows?

Jedno wywołanie zwraca podsumowanie według platform, kategorie problemów, rozkład FPS, przetestowane wersje i najnowsze raporty. Odczytaj compatibility.by_platform.WINDOWS.

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

Odpowiedź (skrócona)

{
  "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. Lista map przetestowanych na Android

Filtruj według typu i platformy. Każdy element zawiera już sumy, przetestowane platformy i ostatnio przetestowaną wersję openOMSI.

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

Odpowiedź (skrócona)

{
  "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. Jako deweloper openOMSI chcę zobaczyć problemy z teksturami w bieżącej wersji

Filtruj raporty według wersji openOMSI i kategorii problemu. Każdy raport zawiera ustrukturyzowane issue_categories oraz opis od testera.

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

Odpowiedź (skrócona)

{
  "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. Wykrycie możliwej regresji między wersjami

compare pokazuje jedną zawartość obok siebie w dwóch wersjach; regressions wymienia każdą zawartość, która wcześniej działała, a teraz zgłasza problemy. Wyniki to jedynie możliwe regresje, nigdy potwierdzone.

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

Odpowiedź (skrócona)

{
  "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. Zasilanie bota Discord

Wyszukaj po nazwie, a następnie zbuduj odpowiedź na podstawie pierwszego elementu: nazwa, platforma, wynik, ostatnio przetestowana wersja i liczba raportów. Buforuj to po swojej stronie.

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

Odpowiedź (skrócona)

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

Sugerowana odpowiedź bota

Grand Paris Moulon
Windows
⚠ Działa z problemami
Ostatnio testowane: 0.1.126
Raporty: 4

6. Jakie problemy są zgłaszane najczęściej na Android?

Endpoint issues agreguje kategorie wraz z liczbą raportów i różnych zawartości; endpoint platformy dodaje najczęściej zgłaszane urządzenia i FPS.

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

Odpowiedź (skrócona)

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

7. Bieżące wydanie i pobieranie

releases/latest zwraca wersję, datę publikacji, adres URL GitHub oraz oficjalne pliki do pobrania według platformy i architektury.

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

Odpowiedź (skrócona)

{
  "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. Znajdowanie zawartości, której nikt jeszcze nie testował

has_reports=false wymienia zatwierdzoną zawartość bez raportów; połącz z type lub q.

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

Odpowiedź (skrócona)

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

Endpointy

Wszystkie ścieżki zaczynają się od https://openomsi.omsimods.com.br/api/public/v1. Pełny opis w formie czytelnej dla maszyn to dokument OpenAPI.

Endpoint	Co zwraca
`GET /meta`	Taksonomie, limity i wersja API.
`GET /status`	Kontrola działania (również objęta limitem: nie odpytuj jej w pętli).
`GET /content`	Wyszukiwanie zawartości z sumami raportów, przetestowanymi platformami i ostatnio przetestowaną wersją dla każdego elementu.
`GET /content/{slug}`	Jedna zawartość w jednym wywołaniu: źródła, zgodność, problemy, wydajność, przetestowane wersje, urządzenia i najnowsze raporty.
`GET /reports`	Pojedyncze raporty z ustrukturyzowanymi kategoriami problemów, FPS, sprzętem i datami.
`GET /compatibility`	Agregacja według wersji openOMSI, platformy lub typu zawartości.
`GET /compatibility/compare`	Jedna zawartość porównana między dwiema wersjami openOMSI.
`GET /compatibility/regressions`	Możliwe regresje między kolejnymi przetestowanymi wersjami.
`GET /issues`	Kategorie problemów uszeregowane według raportów i dotkniętych zawartości.
`GET /platforms/{platform}`	Agregacja dla jednej platformy (android, windows, linux, macos).
`GET /devices`	Sprzęt podany przez testerów, pogrupowany i policzony.
`GET /runtime-reports`	Testy urządzeń samego openOMSI (sesja mogła się nigdy nie rozpocząć): sprzęt, system, jak daleko uruchomienie dotarło, API graficzne, oczyszczony tekst błędu i opcjonalny oczyszczony log. Bez żadnej zawartości.
`GET /runtime-reports/{id}`	Jeden test urządzenia wraz z oczyszczonym logiem, jeśli jest dostępny.
`GET /releases/latest`	Bieżące wydanie i oficjalne pliki do pobrania.
`GET /releases`	Stronicowana historia wydań.

Testy urządzeń nigdy nie ujawniają oryginalnego logu, adresów IP, adresów e-mail, nazw użytkowników ani identyfikatorów kont: tylko dane techniczne i oczyszczony log. To obserwacje społeczności, a nie benchmark ani oficjalne wymaganie.

Filtry, stronicowanie, sortowanie i pola

Stronicowanie: page (od 1) i limit (domyślnie 20, maksymalnie 50). Listy zwracają {"data": [...], "pagination": {page, limit, total, pages}}.
Sortowanie: sort = reports, recent, name, latest_test lub issues; order = asc lub desc.
Opcjonalny parametr fields=name,slug,type zachowuje tylko te pola najwyższego poziomu w każdym elemencie. Domyślna odpowiedź jest już kompletna.
Filtry typów wyliczeniowych nie rozróżniają wielkości liter i przyjmują listy rozdzielone przecinkami (platform=ANDROID,WINDOWS).
Gdy w wyszukiwaniu zawartości użyto filtrów raportów (platform, result, openomsi_version, issue_category), liczniki dotyczą pasujących raportów.

Parametry

Parametr	Opis
`q`	Wyszukiwanie tekstowe w nazwach i aliasach zawartości.
`type`	Typ zawartości. Dozwolona lista rozdzielona przecinkami.
`platform`	Platforma raportu. Dozwolona lista rozdzielona przecinkami.
`result`	Wynik zgłoszony przez testera. Dozwolona lista rozdzielona przecinkami.
`openomsi_version`	Wersja openOMSI, na której przeprowadzono test.
`issue_category`	Kategoria problemu przypisana do raportu (AUDIO jest akceptowane jako alias SOUND). Dozwolona lista rozdzielona przecinkami.
`author`	Autor zawartości (dopasowanie częściowe).
`has_reports`	true: tylko przetestowana zawartość; false: tylko zawartość, której nikt jeszcze nie testował.
`sort`	Pole sortowania.
`order`	Kierunek sortowania.
`page`	Numer strony, licząc od 1.
`limit`	Liczba elementów na stronę (maksymalnie 50).
`fields`	Pola najwyższego poziomu rozdzielone przecinkami, które zostają w każdym elemencie (opcjonalne; domyślnie cały element).
`content`	Slug lub id zawartości (dokładne) albo część jej nazwy.
`architecture`	Architektura procesora w raporcie. Dozwolona lista rozdzielona przecinkami.
`device`	Tekst zawarty w nazwie urządzenia.
`has_fps`	Tylko raporty z wartością FPS (true) lub bez niej (false).
`from`	reports: przetestowano w tej dacie ISO lub później. compare/regressions: starsza wersja openOMSI.
`to`	reports: przetestowano w tej dacie ISO lub wcześniej. compare/regressions: nowsza wersja openOMSI.
`startup_stage`	Jak daleko openOMSI dotarł na urządzeniu. Dozwolona lista rozdzielona przecinkami.
`graphics_backend`	API graficzne wybrane przez testera. Dozwolona lista rozdzielona przecinkami.
`gpu`	Tekst zawarty w nazwie GPU.
`cpu`	Tekst zawarty w nazwie CPU.
`manufacturer`	Producent urządzenia (dopasowanie częściowe).
`device_model`	Model urządzenia (dopasowanie częściowe).
`os_version`	Wersja systemu (dopasowanie częściowe).
`media_indexing_observed`	Android: tester zgłosił, że galeria lub skaner multimediów indeksował obrazy OMSI (true) albo nie (false).
`has_log`	Tylko testy z oczyszczonym logiem (true) lub bez niego (false).
`include_log`	Dołącza sanitized_log do każdego elementu (domyślnie false: lista zawiera tylko has_sanitized_log).

Enumy / Taksonomie

Wygenerowano z własnych list aplikacji. AUDIO jest akceptowane w filtrach jako alias SOUND.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Dane o wydajności

FPS i czasy ładowania to dane ZGŁASZANE PRZEZ UŻYTKOWNIKÓW, a nie kontrolowany benchmark. Statystyki najpierw używają mediany i zawsze zawierają wielkość próby (samples) oraz min i max.

Pamięć podręczna, CORS i wersjonowanie

Odpowiedzi zawierają Cache-Control, ETag i Last-Modified. Przeglądarki mogą je ponownie wykorzystywać przez kilka minut; współdzielone pamięci podręczne muszą ponownie walidować, aby limit był zawsze egzekwowany.
CORS jest otwarty wyłącznie dla GET, HEAD i OPTIONS. Nie ma metod zapisu.
API jest wersjonowane w ścieżce (/api/public/v1). Starsze ścieżki bez wersji przekierowują (308) do v1. Zmiany łamiące zgodność będą wydawane wyłącznie jako nowa wersja.
Strona openOMSI Compatibility odczytuje własną bazę danych bezpośrednio i nigdy nie korzysta z tego API ani jego limitu.

Wytyczne integracji

Buforuj dane lokalnie.
Unikaj pollingu; wysyłaj zapytania tylko wtedy, gdy to potrzebne.
Używaj endpointów zbiorczych (szczegóły zawartości, zgodność, problemy, platformy).
Przestrzegaj Retry-After i nagłówków RateLimit-*.
Nie scrapuj HTML, gdy API udostępnia równoważne dane.
Nie wnioskuj o potwierdzonych błędach silnika na podstawie raportów społeczności.
Zawsze uwzględniaj wersję openOMSI w swoich analizach.

O danych

Raporty społeczności to obserwacje, a nie miarodajna certyfikacja zgodności. Pojedynczy raport nie oznacza, że "ten mod jest zgodny", ani że "to błąd openOMSI". Weź pod uwagę liczbę próbek, wersję openOMSI, platformę, sprzęt, wersję zawartości, kategorię problemu i spójność między raportami.

Prywatność

Odpowiedzi nigdy nie zawierają identyfikatorów Discord, adresów e-mail, adresów IP, sesji, subskrypcji powiadomień, danych moderacji ani identyfikatorów urządzeń. Raporty pokazują tylko publiczną nazwę wyświetlaną i sprzęt, który tester zdecydował się opublikować. W raporcie issue_categories jest ustrukturyzowane, natomiast issue_description to jedyny opis tekstowy testera dla całego raportu.

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