Zovo Bingo Card Maker

Use this when the user wants printable bingo cards: a bingo card generator or bingo card maker for a holiday party, classroom, baby shower, team meeting, or any game with their own words or phrases, or classic number bingo (1-75) or UK 90-ball tickets. Makes 1-200 different cards (3x3, 4x4 or 5x5, free centre on or off) with each item spread evenly, optionally so that no two cards share a winning line. Returns card 1, balance and uniqueness numbers, and links to a cards PDF (1, 2, 4 or 6 per page, cut lines), a caller sheet PDF and a CSV. Does not add pictures, and does not draw items or check claims (use show_bingo_caller). Not for a single personal goals card (use generate_goal_bingo) or for prize or money games.

{
  "type": "object",
  "properties": {
    "mode": {
      "description": "words (default): your own words or phrases. numbers_75: classic US bingo, 5x5 with B 1-15, I 16-30, N 31-45, G 46-60, O 61-75. numbers_90: UK-style 3x9 tickets with 15 numbers from 1-90, printed in strips of 6. Example: words.",
      "type": "string",
      "enum": [
        "words",
        "numbers_75",
        "numbers_90"
      ]
    },
    "items": {
      "description": "For mode words: the words or phrases to put on the cards, one per entry, e.g. [\"Ugly sweater\", \"Mistletoe\", \"Hot cocoa\"]. Need at least 24 for 5x5 with a free centre, 25 without, 16 for 4x4, 8 or 9 for 3x3. Up to 300, each up to 100 characters.",
      "maxItems": 400,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 4000
          },
          {
            "type": "number"
          }
        ]
      }
    },
    "card_count": {
      "description": "How many different cards (or tickets) to make, 1-200, e.g. 30. Default 30.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "grid_size": {
      "description": "Card size for mode words: 3, 4 or 5 (default 5), e.g. 5. Classic numbers_75 is always 5x5; numbers_90 tickets are always 3x9.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "free_space": {
      "description": "Free centre square on 3x3 and 5x5 cards, e.g. true. Default true for 5x5 and false for 3x3; 4x4 cards have no centre.",
      "type": "boolean"
    },
    "free_label": {
      "description": "Text in the free centre square, e.g. FREE (default), Santa, or Baby.",
      "type": "string",
      "maxLength": 40
    },
    "title": {
      "description": "Heading printed on every card, e.g. Holiday Party Bingo. Default Bingo.",
      "type": "string",
      "maxLength": 120
    },
    "accent_color": {
      "description": "Theme colour as hex or a name, e.g. #2B8A3E, red, green, gold, pink, purple, teal, christmas. Default raspberry #C2255C.",
      "type": "string",
      "maxLength": 30
    },
    "unique_lines": {
      "description": "true = no two cards share an identical winning line (row, column or diagonal), so two players never complete the very same line. Needs enough items; the tool explains if the request is not possible. Default false (cards are always all different).",
      "type": "boolean"
    },
    "paper": {
      "description": "Paper size for the PDFs, e.g. letter (default) or a4.",
      "type": "string",
      "enum": [
        "letter",
        "a4"
      ]
    },
    "cards_per_page": {
      "description": "Cards per printed page: 1, 2, 4 or 6, e.g. 2. Default 2 (6 for 90-ball tickets). Pages get dashed cut lines.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "seed": {
      "description": "Card set number from an earlier result, e.g. 4242. The same items, options and seed always rebuild the same cards. Leave out for a new random set.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "view": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "mode": {
      "type": "string"
    },
    "grid": {
      "type": "string"
    },
    "free_space": {
      "type": "boolean"
    },
    "free_label": {
      "type": "string"
    },
    "card_count": {
      "type": "number"
    },
    "item_count": {
      "type": "number"
    },
    "cells_per_card": {
      "type": "number"
    },
    "balance": {
      "type": "object",
      "properties": {
        "min_cards_per_item": {
          "type": "number"
        },
        "max_cards_per_item": {
          "type": "number"
        },
        "spread": {
          "type": "number"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "min_cards_per_item",
        "max_cards_per_item",
        "spread",
        "note"
      ],
      "additionalProperties": false
    },
    "uniqueness": {
      "type": "object",
      "properties": {
        "all_cards_different": {
          "type": "boolean"
        },
        "distinct_item_sets": {
          "type": "number"
        },
        "unique_lines": {
          "type": "boolean"
        },
        "cards_sharing_a_line": {
          "type": "number"
        }
      },
      "required": [
        "all_cards_different",
        "distinct_item_sets",
        "unique_lines",
        "cards_sharing_a_line"
      ],
      "additionalProperties": false
    },
    "seed": {
      "type": "number"
    },
    "card_1": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "caller_args": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "pdf_pages": {
      "type": "number"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "downloads": {
      "type": "object",
      "properties": {
        "cards_pdf": {
          "type": "string"
        },
        "caller_pdf": {
          "type": "string"
        },
        "csv": {
          "type": "string"
        }
      },
      "required": [
        "cards_pdf",
        "caller_pdf",
        "csv"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "view",
    "title",
    "mode",
    "grid",
    "free_space",
    "free_label",
    "card_count",
    "item_count",
    "cells_per_card",
    "balance",
    "uniqueness",
    "seed",
    "card_1",
    "caller_args",
    "pdf_pages",
    "warnings",
    "downloads"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user is running a bingo game: call or draw the next word or number at random, show what has been called on a big screen, check whether a claimed bingo on card number N is real (which line, at which call, and who won first), or list all cards that have bingo now. Pass the same items and the caller_args (mode, grid_size, free_space, card_count, seed, unique_lines) from generate_bingo_cards, plus everything called so far in order. Draws use secure randomness. Does not make or print cards and does not keep game state between calls: always send the full called list. Not for prize, betting or money games.

{
  "type": "object",
  "properties": {
    "mode": {
      "description": "words (default): your own words or phrases. numbers_75: classic US bingo, 5x5 with B 1-15, I 16-30, N 31-45, G 46-60, O 61-75. numbers_90: UK-style 3x9 tickets with 15 numbers from 1-90, printed in strips of 6. Example: words.",
      "type": "string",
      "enum": [
        "words",
        "numbers_75",
        "numbers_90"
      ]
    },
    "items": {
      "description": "For mode words: the words or phrases to put on the cards, one per entry, e.g. [\"Ugly sweater\", \"Mistletoe\", \"Hot cocoa\"]. Need at least 24 for 5x5 with a free centre, 25 without, 16 for 4x4, 8 or 9 for 3x3. Up to 300, each up to 100 characters.",
      "maxItems": 400,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 4000
          },
          {
            "type": "number"
          }
        ]
      }
    },
    "grid_size": {
      "description": "Card size for mode words: 3, 4 or 5 (default 5), e.g. 5. Classic numbers_75 is always 5x5; numbers_90 tickets are always 3x9.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "free_space": {
      "description": "Free centre square on 3x3 and 5x5 cards, e.g. true. Default true for 5x5 and false for 3x3; 4x4 cards have no centre.",
      "type": "boolean"
    },
    "card_count": {
      "description": "How many different cards (or tickets) to make, 1-200, e.g. 30. Default 30.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "seed": {
      "description": "Card set number from an earlier result, e.g. 4242. The same items, options and seed always rebuild the same cards. Leave out for a new random set.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "unique_lines": {
      "description": "true = no two cards share an identical winning line (row, column or diagonal), so two players never complete the very same line. Needs enough items; the tool explains if the request is not possible. Default false (cards are always all different).",
      "type": "boolean"
    },
    "list_code": {
      "description": "For word games: list_code from caller_args of generate_bingo_cards, e.g. 0k3x9qa. Confirms the items were sent in the same order as when the cards were made, so card numbers match.",
      "type": "string",
      "maxLength": 16
    },
    "called": {
      "description": "Everything already called, in call order, exactly as shown on the cards, e.g. [\"Mistletoe\", \"Hot cocoa\"] or [\"B-12\", \"N-40\", \"O-71\"]. Empty for a new game.",
      "maxItems": 400,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 4000
          },
          {
            "type": "number"
          }
        ]
      }
    },
    "action": {
      "description": "draw (default): call the next item at random. check: verify a claimed bingo on card_number. winners: list every card that has the pattern now. board: show what has been called. Example: check.",
      "type": "string",
      "enum": [
        "draw",
        "check",
        "winners",
        "board"
      ]
    },
    "card_number": {
      "description": "For action check: the card number printed on the claimed card, e.g. 17.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "pattern": {
      "description": "Winning pattern to check, e.g. line. line: any row, column or diagonal (90-ball: any row). two_lines: two complete lines. four_corners: the 4 corner squares (not for 90-ball). full_card: every square (full house). Default line.",
      "type": "string",
      "enum": [
        "line",
        "two_lines",
        "four_corners",
        "full_card"
      ]
    },
    "title": {
      "description": "Game title shown on the caller screen, e.g. Holiday Party Bingo.",
      "type": "string",
      "maxLength": 120
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "view": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "mode": {
      "type": "string"
    },
    "action": {
      "type": "string"
    },
    "total_items": {
      "type": "number"
    },
    "called_count": {
      "type": "number"
    },
    "remaining": {
      "type": "number"
    },
    "current": {
      "type": [
        "string",
        "null"
      ]
    },
    "called": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "pattern": {
      "type": "string"
    },
    "check": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "winners": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "card": {
                "type": "number"
              },
              "at_call": {
                "type": "number"
              }
            },
            "required": [
              "card",
              "at_call"
            ],
            "additionalProperties": false
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "caller_args": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "view",
    "title",
    "mode",
    "action",
    "total_items",
    "called_count",
    "remaining",
    "current",
    "called",
    "pattern",
    "check",
    "winners",
    "caller_args"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user wants a goal bingo card (new year goal bingo, 2027 bingo card, resolutions bingo, bucket-list bingo): one personal 5x5 card (or 4x4, 3x3) of their own goals with a free centre, title, year and theme colour, as a PNG, SVG and printable PDF. Goals marked completed print with a check mark and the tool counts bingo lines. Needs one goal per square (24 for 5x5 with a free centre). Does not invent goals for the user and does not make sets of party cards (use generate_bingo_cards).

{
  "type": "object",
  "properties": {
    "goals": {
      "maxItems": 40,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 4000
          },
          {
            "type": "number"
          }
        ]
      },
      "description": "The goals, one per square, e.g. [\"Run a 10K\", \"Read 12 books\", \"Learn to make sourdough\"]. Exactly 24 for a 5x5 card with a free centre (25 without), 16 for 4x4, 8 for 3x3 with a free centre (9 without). Up to 80 characters each."
    },
    "year": {
      "description": "Year for the title, e.g. 2027 gives \"2027 Bingo\".",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "title": {
      "description": "Card heading, e.g. Maya's 2027 Bingo. Overrides the year title.",
      "type": "string",
      "maxLength": 120
    },
    "subtitle": {
      "description": "Small line under the title, e.g. One square at a time.",
      "type": "string",
      "maxLength": 120
    },
    "grid_size": {
      "description": "3, 4 or 5 (default 5), e.g. 5.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "free_space": {
      "description": "Free centre square on 3x3 and 5x5 cards, e.g. true (default).",
      "type": "boolean"
    },
    "center_label": {
      "description": "Text in the centre square, e.g. FREE (default), Be kind to myself, or 2027.",
      "type": "string",
      "maxLength": 40
    },
    "shuffle": {
      "description": "true to mix the goals into a random order, e.g. false (default keeps your order, filled row by row).",
      "type": "boolean"
    },
    "seed": {
      "description": "Shuffle number from an earlier result to repeat the same order, e.g. 77.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "completed": {
      "description": "Goals already done, written as in goals, e.g. [\"Read 12 books\"]. They print with a check mark and count toward bingo lines.",
      "maxItems": 40,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 4000
          },
          {
            "type": "number"
          }
        ]
      }
    },
    "accent_color": {
      "description": "Theme colour as hex or a name, e.g. #0B7285, teal, gold, purple. Default raspberry #C2255C.",
      "type": "string",
      "maxLength": 30
    },
    "paper": {
      "description": "Paper size for the PDF, e.g. letter (default) or a4.",
      "type": "string",
      "enum": [
        "letter",
        "a4"
      ]
    }
  },
  "required": [
    "goals"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "view": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "subtitle": {
      "type": "string"
    },
    "grid_size": {
      "type": "number"
    },
    "cells": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "center_index": {
      "type": "number"
    },
    "done": {
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "done_count": {
      "type": "number"
    },
    "goal_count": {
      "type": "number"
    },
    "bingo_lines": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "seed": {
      "type": [
        "number",
        "null"
      ]
    },
    "accent": {
      "type": "string"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "downloads": {
      "type": "object",
      "properties": {
        "png": {
          "type": "string"
        },
        "svg": {
          "type": "string"
        },
        "pdf": {
          "type": "string"
        }
      },
      "required": [
        "png",
        "svg",
        "pdf"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "view",
    "title",
    "subtitle",
    "grid_size",
    "cells",
    "center_index",
    "done",
    "done_count",
    "goal_count",
    "bingo_lines",
    "seed",
    "accent",
    "warnings",
    "downloads"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}