{
  "openapi": "3.1.1",
  "info": {
    "title": "Sizewise Scale Comparison API",
    "version": "1.0.0",
    "summary": "Line up buildings, animals, planets or atoms side by side, drawn to true scale.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://sizewisescalecompare.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Line up buildings, animals, planets or atoms side by side, drawn to true scale.",
        "description": "Compares the sizes of up to 24 things — from atoms and viruses to skyscrapers, stars and galaxies — and draws them to the same scale or as pairs with the ratio between neighbours. 337 objects come from Wikidata with their sources; add your own as “Name = 1.8 m”.\n\nMethodology:\n- Each object’s size is one Wikidata statement: height (P2048), length (P2043), width (P2049), diameter (P2386, or twice the radius P2120), wingspan (P2050), summit elevation (P2044) or atomic radius (P14936, doubled). The curation script took the preferred statement, else the largest statement without qualifiers, unless a specific one was chosen (for example a building’s height to the tip of its spire as listed).\n- True scale: every object gets the same metres per pixel, so the largest one fills the drawing height; anything below one pixel is marked as too small to see.\n- Pairs: each neighbour pair is drawn at its own scale with the ratio between them, which keeps sizes 10^30 apart readable.\n- Silhouettes are generic shapes drawn for Sizewise; only the measured dimension is to scale (the other side uses the object’s own second dimension when Wikidata has one).\n\nSizes of animals and dinosaurs vary between individuals and estimates; Wikidata values can be maximum or typical sizes. Each row names the exact statement, so you can check it.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "sizewise_scale_compare",
        "x-owner-app": "sizewise",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SizewiseScaleCompareInput"
              },
              "examples": {
                "example1": {
                  "summary": "Landmarks and you",
                  "value": {
                    "objects": "Statue of Liberty, Eiffel Tower, Burj Khalifa, Me = 1.8 m",
                    "sort": "size",
                    "layout": "true-scale"
                  }
                },
                "example2": {
                  "summary": "From an atom to the universe, in pairs",
                  "value": {
                    "objects": "Hydrogen atom, Red blood cell, Golf ball, Blue whale, Mount Everest, Earth, Sun, Milky Way",
                    "layout": "pairs"
                  }
                },
                "example3": {
                  "summary": "The planets",
                  "value": {
                    "objects": "Mercury, Mars, Venus, Earth, Neptune, Uranus, Saturn (without rings), Jupiter",
                    "title": "Planets to scale"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SizewiseScaleCompareResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SizewiseScaleCompareInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "objects": {
            "title": "Objects (comma or new line between them)",
            "description": "Names from the Sizewise list (for example Blue whale, Earth, Burj Khalifa), Wikidata IDs such as Q243, or your own object as “Name = 9 m”.",
            "type": "string",
            "maxLength": 3000,
            "default": "Statue of Liberty, Eiffel Tower, Burj Khalifa, Me = 1.8 m"
          },
          "sort": {
            "title": "Order",
            "type": "string",
            "enum": [
              "size",
              "input"
            ],
            "default": "size"
          },
          "layout": {
            "title": "Drawing",
            "type": "string",
            "enum": [
              "true-scale",
              "pairs"
            ],
            "default": "true-scale"
          },
          "title": {
            "title": "Title on the drawing",
            "type": "string",
            "maxLength": 80,
            "default": ""
          }
        },
        "required": []
      },
      "SizewiseScaleCompareResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object"
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}