Pbbg.site json api structure

Pbbg.site json api structure

We discussed about two months ago on Discord about PBBGs who wanted to provide a JSON API for the pbbg.site directory and what the API should look like.

I dug up the schema I made.

  name: string
  ?version: string
  ?description: string
  ?tags: string[]
  ?status: string ('up'/'down'/other)
  dates: {
    born: "Y-m-d"
    ?updated: "Y-m-d"
  players: {
    registered: int
    ?active: int
  ?links: {
    production: string
    beta: string
    github: string
    ...: string

Here’s OpenDominion’s implementation as an example for the above schema: https://beta.opendominion.net/api/v1/pbbg

Let me know what you think.


Given our recent talk about expanding pbbg.site, this would be a cool addition, though I would change a couple of things.

Status should be given by pbbg, not relied upon by the response, unless it’s like a custom status? I imagine status as like whether it’s actually online or offline via ping test or something similar.

Change “born” to “created”.

Updated could be an object with a link to the latest update.

In the links section it looks as if links is optional, but the children are not. Other than that it looks like a nice little schema :slight_smile:

1 Like

Looking back at it, ‘born’ should definitely be ‘created’ instead. But despite that I don’t know if such a format will ever be adopted, or useful even.

I have hopes that it will in the future

I’ve implemented this for Imperial Conflict here: https://imperialconflict.com/pbbg

  "name": "Imperial Conflict",
  "description": "Imperial Conflict is a free online browser-based massively multiplayer online strategy game set in space. Players interact in cooperation and against other players in a quest to \"Rule The Galaxy\".",
  "tags": [
  "players": {
    "registered": 49387,
    "active": 248
  "links": {
    "website": "https://imperialconflict.com",
    "forum": "https://discourse.imperialconflict.com",
    "discord": "https://discord.gg/yVZjc4M",
    "patreon": "https://www.patreon.com/imperialconflict",
    "facebook": "https://www.facebook.com/imperialconflict/",
    "twitter": "https://twitter.com/ic_game",
    "reddit": "https://www.reddit.com/r/ImperialConflict/",
    "pbbg.com": "https://pbbg.com/games/imperial-conflict",
    "PBBG Wiki": "https://wiki.pbbg.com/wiki/Imperial_Conflict"
  "data": {
    "empires": {
      "active": 301
    "galaxies": {
      "active": 4
    "patreon_subscriber_credits": [

Some thoughts:


Our start date isn’t clear given our original owner didn’t document that, so I’m not yet sure what to put here. I could guess reasonably well but I’d imagine there are others out there with this issue. I left it out for now, and recommend making it optional.


I added a freeform “data” to reflect some misc data that is relevant meta info but may not be shared with other games. For me, this is counts for active “empires” (sub-accounts) and “galaxies”, as well as patreon subscribers.

We got some feedback on this example from Pirion on Discord, he had a good point about abstracting some of this into generic data. Patreon subscriber data in particular may be better suited in some kind of credits block alongside staff info.

This site has some serious issues that must be fixed immediately! This is most alarming.

1 Like

Directory entry is about OpenDominion and not about original Dominion game, so I think you can safely use creation date of your project instead of creation date of Dominion.
And if you do not remember that, I think date of first commit will be a good approximation.

Ah, I mean that we don’t have complete history for Imperial Conflict’s codebase. It didn’t even make it into proper version control until years after it launched. :grimacing:

We have a few guesses from archive.org, but nothing I am too confident about.

Sorry, I totally confused you with @WaveHack :sweat_smile:

No worries! We’re both good looking, It’s an understandable mistake.