{
  "openapi": "3.1.1",
  "info": {
    "title": "Cartograph Country Facts (capital, population, area, languages, neighbours) API",
    "version": "1.0.0",
    "summary": "A dated fact card for any country: capital, population, area, languages, neighbours and flag.",
    "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://cartographcountryfacts.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "A dated fact card for any country: capital, population, area, languages, neighbours and flag.",
        "description": "Shows a fact card for one of 197 countries — capital, population with its estimate year, area, population density, rank in the world, official languages, land neighbours, the flag and its description — with a map of the country and its neighbours, and optionally compares it with a second country. Facts come from the final edition of The World Factbook (public domain) and Wikidata. It is the facts engine of the Cartograph app.\n\nMethodology:\n- Capital, population estimate (with its year), total area (land and water), land borders and the flag description come from the final edition of The World Factbook (CIA, archived in February 2026, public domain). Borders are made symmetric; borders of overseas parts count for their country (France borders Brazil and Suriname through French Guiana).\n- Official languages and the capitals that the Factbook had out of date come from Wikidata (CC0). Palestine combines the Factbook’s West Bank and Gaza Strip entries.\n- Density = population ÷ total area. Ranks count the 197 countries of the atlas (1 = largest).\n- Map: Natural Earth 1:110m outlines, which show de-facto boundaries; disputed borders are not endorsed.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "cartograph_country_facts",
        "x-owner-app": "cartograph",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CartographCountryFactsInput"
              },
              "examples": {
                "example1": {
                  "summary": "France",
                  "value": {
                    "country": "France"
                  }
                },
                "example2": {
                  "summary": "Japan compared with Germany",
                  "value": {
                    "country": "JP",
                    "compare": "DE"
                  }
                },
                "example3": {
                  "summary": "Mongolia and its two neighbours",
                  "value": {
                    "country": "Mongolia"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CartographCountryFactsResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "CartographCountryFactsInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "country": {
            "title": "Country (English name or ISO code)",
            "type": "string",
            "maxLength": 60,
            "default": "France"
          },
          "compare": {
            "title": "Compare with (optional)",
            "type": "string",
            "maxLength": 60,
            "default": ""
          }
        },
        "required": []
      },
      "CartographCountryFactsResult": {
        "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",
            "additionalProperties": false,
            "required": [
              "facts",
              "compare",
              "ratios",
              "source",
              "openInApp"
            ],
            "properties": {
              "facts": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "iso2",
                  "iso3",
                  "name",
                  "region",
                  "status",
                  "capital",
                  "capitalAlt",
                  "population",
                  "populationYear",
                  "areaKm2",
                  "densityPerKm2",
                  "populationRank",
                  "areaRank",
                  "languages",
                  "neighbours",
                  "flag"
                ],
                "properties": {
                  "iso2": {
                    "type": "string"
                  },
                  "iso3": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "capital": {
                    "type": "string"
                  },
                  "capitalAlt": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "population": {
                    "type": "integer"
                  },
                  "populationYear": {
                    "type": "integer"
                  },
                  "areaKm2": {
                    "type": "number"
                  },
                  "densityPerKm2": {
                    "type": "number"
                  },
                  "populationRank": {
                    "type": "integer",
                    "description": "Among the 197 countries."
                  },
                  "areaRank": {
                    "type": "integer"
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "neighbours": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "flag": {
                    "type": "string",
                    "description": "Flag description (World Factbook)."
                  }
                }
              },
              "compare": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": false,
                "required": [
                  "iso2",
                  "iso3",
                  "name",
                  "region",
                  "status",
                  "capital",
                  "capitalAlt",
                  "population",
                  "populationYear",
                  "areaKm2",
                  "densityPerKm2",
                  "populationRank",
                  "areaRank",
                  "languages",
                  "neighbours",
                  "flag"
                ],
                "properties": {
                  "iso2": {
                    "type": "string"
                  },
                  "iso3": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "capital": {
                    "type": "string"
                  },
                  "capitalAlt": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "population": {
                    "type": "integer"
                  },
                  "populationYear": {
                    "type": "integer"
                  },
                  "areaKm2": {
                    "type": "number"
                  },
                  "densityPerKm2": {
                    "type": "number"
                  },
                  "populationRank": {
                    "type": "integer",
                    "description": "Among the 197 countries."
                  },
                  "areaRank": {
                    "type": "integer"
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "neighbours": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "flag": {
                    "type": "string",
                    "description": "Flag description (World Factbook)."
                  }
                }
              },
              "ratios": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": false,
                "required": [
                  "population",
                  "area",
                  "density"
                ],
                "properties": {
                  "population": {
                    "type": "number"
                  },
                  "area": {
                    "type": "number"
                  },
                  "density": {
                    "type": "number"
                  }
                },
                "description": "Country ÷ comparison country."
              },
              "source": {
                "type": "string"
              },
              "openInApp": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}