API pubblica

Accesso strutturato e di sola lettura ai report di compatibilità della community su mappe, bus, veicoli, mod, oggetti, plugin e strumenti eseguiti su openOMSI. Pensata per sviluppatori di openOMSI, strumenti di analisi, bot e integrazioni.

Questa NON è un'API per segnalare bug di openOMSI. I bug del motore stesso vanno segnalati sui canali ufficiali del progetto. Qui si legge solo ciò che la community ha testato.

⚠ LIMITE DI RICHIESTE DELL'API PUBBLICA

6 richieste per IP ogni 60 minuti

Questa API ha volutamente un limite di richieste molto rigido perché è pubblica e non richiede autenticazione.

Progetta le integrazioni in modo da memorizzare le risposte in cache in locale.
Non interrogare l'API in modo continuo.
Usa gli endpoint aggregati ogni volta che è possibile: una sola chiamata risponde alla maggior parte delle domande.

Il limite è condiviso da tutti gli endpoint pubblici e si applica solo ai consumatori esterni; il sito web stesso non usa questa quota.

Guida rapida

URL di base: https://openomsi.omsimods.com.br/api/public/v1. Tutto è JSON, solo GET, senza autenticazione. Inizia dall'endpoint meta per scoprire i valori esatti accettati dai filtri.

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)

Limite di richieste, header ed errori

Ogni risposta contiene RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Superato il limite, l'API risponde 429 con Retry-After (secondi).
Le richieste condizionali (If-None-Match / If-Modified-Since) restituiscono 304 senza corpo, ma un 304 conta comunque nella quota.
Gli errori usano sempre lo stesso formato {"error": code, "message": text}; stati 400, 404, 429 e 500. Non vengono mai restituiti stack trace.

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
}

Casi d'uso pratici

I valori di esempio sono indicativi; la struttura delle risposte è reale.

1. Grand Paris Moulon funziona su Windows?

Una sola chiamata restituisce il riepilogo per piattaforma, le categorie di problemi, la distribuzione degli FPS, le versioni testate e gli ultimi report. Leggi compatibility.by_platform.WINDOWS.

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

Risposta (abbreviata)

{
  "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. Elencare le mappe testate su Android

Filtra per tipo e piattaforma. Ogni elemento include già i totali, le piattaforme testate e l'ultima versione di openOMSI testata.

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

Risposta (abbreviata)

{
  "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. Come sviluppatore di openOMSI, vedere i problemi di texture nella versione attuale

Filtra i report per versione di openOMSI e categoria di problema. Ogni report elenca issue_categories strutturato insieme alla descrizione del tester.

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

Risposta (abbreviata)

{
  "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. Rilevare una possibile regressione tra versioni

compare mostra uno stesso contenuto affiancato in due versioni; regressions elenca ogni contenuto che prima funzionava e ora segnala problemi. I risultati sono solo possibili regressioni, mai confermate.

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

Risposta (abbreviata)

{
  "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. Alimentare un bot Discord

Cerca per nome, poi costruisci la risposta dal primo elemento: nome, piattaforma, risultato, ultima versione testata e numero di report. Memorizzalo in cache dal tuo lato.

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

Risposta (abbreviata)

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

Risposta suggerita per il bot

Grand Paris Moulon
Windows
⚠ Funziona con problemi
Ultimi testati: 0.1.126
Report: 4

6. Quali problemi vengono segnalati più spesso su Android?

L'endpoint issues aggrega le categorie con il numero di report e di contenuti distinti; l'endpoint della piattaforma aggiunge i dispositivi più segnalati e gli 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

Risposta (abbreviata)

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

7. Rilascio attuale e download

releases/latest restituisce la versione, la data di pubblicazione, l'URL GitHub e gli asset di download ufficiali per piattaforma e architettura.

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

Risposta (abbreviata)

{
  "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. Trovare contenuti che nessuno ha ancora testato

has_reports=false elenca i contenuti approvati senza report; combinalo con type o q.

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

Risposta (abbreviata)

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

Endpoint

Tutti i percorsi iniziano con https://openomsi.omsimods.com.br/api/public/v1. La descrizione completa leggibile da macchina è il documento OpenAPI.

Endpoint	Cosa restituisce
`GET /meta`	Tassonomie, limiti e versione dell'API.
`GET /status`	Controllo operativo (anch'esso limitato: non interrogarlo ripetutamente).
`GET /content`	Ricerca di contenuti con totali dei report, piattaforme testate e ultima versione testata per elemento.
`GET /content/{slug}`	Un contenuto in una sola chiamata: fonti, compatibilità, problemi, prestazioni, versioni testate, dispositivi e ultimi report.
`GET /reports`	Report singoli con categorie di problemi strutturate, FPS, hardware e date.
`GET /compatibility`	Aggregato per versione di openOMSI, piattaforma o tipo di contenuto.
`GET /compatibility/compare`	Un contenuto confrontato tra due versioni di openOMSI.
`GET /compatibility/regressions`	Possibili regressioni tra versioni testate consecutive.
`GET /issues`	Categorie di problemi ordinate per report e contenuti interessati.
`GET /platforms/{platform}`	Aggregato per una piattaforma (android, windows, linux, macos).
`GET /devices`	Hardware inserito dai tester, raggruppato e conteggiato.
`GET /runtime-reports`	Test su dispositivo di openOMSI stesso (la sessione potrebbe non essere mai iniziata): hardware, sistema operativo, fino a dove è arrivato, API grafica, testo dell'errore sanitizzato e log sanitizzato facoltativo. Nessun contenuto coinvolto.
`GET /runtime-reports/{id}`	Un test su dispositivo, con il suo log sanitizzato quando presente.
`GET /releases/latest`	Rilascio attuale e asset di download ufficiali.
`GET /releases`	Cronologia dei rilasci paginata.

I test su dispositivo non espongono mai il log originale, gli indirizzi IP, le e-mail, i nomi utente né gli identificatori di account: solo dati tecnici e il log sanitizzato. Sono osservazioni della community, non un benchmark né un requisito ufficiale.

Filtri, paginazione, ordinamento e campi

Paginazione: page (da 1) e limit (predefinito 20, massimo 50). Le liste rispondono {"data": [...], "pagination": {page, limit, total, pages}}.
Ordinamento: sort = reports, recent, name, latest_test o issues; order = asc o desc.
Il parametro facoltativo fields=name,slug,type mantiene solo quei campi di primo livello di ogni elemento. La risposta predefinita è già completa.
I filtri enum non distinguono maiuscole e minuscole e accettano elenchi separati da virgole (platform=ANDROID,WINDOWS).
Quando nella ricerca di contenuti si usano filtri sui report (platform, result, openomsi_version, issue_category), i conteggi si riferiscono ai report corrispondenti.

Parametri

Parametro	Descrizione
`q`	Ricerca testuale nei nomi e negli alias dei contenuti.
`type`	Tipo di contenuto. È consentito un elenco separato da virgole.
`platform`	Piattaforma del report. È consentito un elenco separato da virgole.
`result`	Risultato segnalato dal tester. È consentito un elenco separato da virgole.
`openomsi_version`	Versione di openOMSI su cui è stato eseguito il test.
`issue_category`	Categoria di problema associata al report (AUDIO è accettato come alias di SOUND). È consentito un elenco separato da virgole.
`author`	Autore del contenuto (corrispondenza parziale).
`has_reports`	true: solo contenuti testati; false: solo contenuti che nessuno ha ancora testato.
`sort`	Campo di ordinamento.
`order`	Direzione di ordinamento.
`page`	Numero di pagina, a partire da 1.
`limit`	Elementi per pagina (massimo 50).
`fields`	Campi di primo livello separati da virgole da mantenere in ogni elemento (facoltativo; per impostazione predefinita l'elemento completo).
`content`	Slug o id del contenuto (esatto), o parte del suo nome.
`architecture`	Architettura CPU del report. È consentito un elenco separato da virgole.
`device`	Testo contenuto nel nome del dispositivo.
`has_fps`	Solo report con (true) o senza (false) valore FPS.
`from`	reports: testato in questa data ISO o dopo. compare/regressions: versione di openOMSI più vecchia.
`to`	reports: testato in questa data ISO o prima. compare/regressions: versione di openOMSI più recente.
`startup_stage`	Fino a dove è arrivato openOMSI sul dispositivo. È consentito un elenco separato da virgole.
`graphics_backend`	API grafica scelta dal tester. È consentito un elenco separato da virgole.
`gpu`	Testo contenuto nel nome della GPU.
`cpu`	Testo contenuto nel nome della CPU.
`manufacturer`	Produttore del dispositivo (corrispondenza parziale).
`device_model`	Modello del dispositivo (corrispondenza parziale).
`os_version`	Versione del sistema operativo (corrispondenza parziale).
`media_indexing_observed`	Android: il tester ha segnalato che la galleria o lo scanner multimediale stava indicizzando le immagini di OMSI (true) oppure no (false).
`has_log`	Solo test con (true) o senza (false) log sanitizzato.
`include_log`	Include sanitized_log in ogni elemento (predefinito false: l'elenco indica solo has_sanitized_log).

Enum / Tassonomie

Generato dalle liste della stessa applicazione. AUDIO è accettato come alias di SOUND nei filtri.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Dati sulle prestazioni

FPS e tempi di caricamento sono dati SEGNALATI DAGLI UTENTI, non un benchmark controllato. Le statistiche usano prima la mediana e includono sempre la dimensione del campione (samples), oltre a min e max.

Cache, CORS e versionamento

Le risposte contengono Cache-Control, ETag e Last-Modified. I browser possono riutilizzarle per qualche minuto; le cache condivise devono rivalidare in modo che la quota venga sempre applicata.
CORS è aperto solo per GET, HEAD e OPTIONS. Non esistono metodi di scrittura.
L'API è versionata nel percorso (/api/public/v1). I vecchi percorsi senza versione reindirizzano (308) a v1. Le modifiche non retrocompatibili verranno rilasciate solo come nuova versione.
Il sito web openOMSI Compatibility legge direttamente il proprio database e non usa mai questa API né la sua quota.

Linee guida per l'integrazione

Memorizza i dati in cache in locale.
Evita il polling; effettua richieste solo quando serve.
Usa gli endpoint aggregati (dettaglio contenuto, compatibilità, problemi, piattaforme).
Rispetta Retry-After e gli header RateLimit-*.
Non fare scraping dell'HTML quando l'API offre dati equivalenti.
Non dedurre bug confermati del motore dai report della community.
Mantieni sempre la versione di openOMSI nelle tue analisi.

Informazioni sui dati

I report della community sono osservazioni, non una certificazione di compatibilità autorevole. Un singolo report non significa "questa mod è compatibile" né "questo è un bug di openOMSI". Considera il numero di campioni, la versione di openOMSI, la piattaforma, l'hardware, la versione del contenuto, la categoria del problema e la coerenza tra i report.

Privacy

Le risposte non includono mai ID Discord, e-mail, indirizzi IP, sessioni, iscrizioni alle notifiche, dati di moderazione o identificatori di dispositivo. I report mostrano solo il nome pubblico e l'hardware che il tester ha scelto di pubblicare. In un report, issue_categories è strutturato mentre issue_description è l'unica descrizione a testo libero del tester per l'intero report.

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