API & MCP

Everything a person can do on Cartograph Flag Finder (find a flag by its colours and layout), a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://cartographflagfinder.usefulweb.site/api/v1/calculate – run Cartograph Flag Finder (find a flag by its colours and layout)
GET https://cartographflagfinder.usefulweb.site/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Cartograph Flag Finder (find a flag by its colours and layout)

Finds the flags of 197 countries by their colours (red, dark red, orange, yellow, green, blue, light blue, white, black), their layout (horizontal, vertical or diagonal stripes, cross, saltire, canton, hoist triangle, border) and their symbols (disc, star, crescent, sun, coat of arms, writing, map, Union Jack, animal, plant, weapon), optionally with the number of stripes and a region. Every flag gets a score from 0 to 100; the best matches are shown with their flags. It is the flag-finder engine of the Cartograph app.

Inputs of Cartograph Flag Finder (find a flag by its colours and layout)
Field	Type	Default	Description
`colours`	multiselect (red, maroon, orange, yellow, green, blue, lightblue, white, black)	["red","white","blue"]	Colours in the flag
`features`	multiselect (hstripes, vstripes, diagonal, cross, saltire, canton, triangle, border, plain, disc, star, crescent, sun, emblem, text, map, unionjack, animal, plant, weapon)	[]	Layout and symbols
`bands`	integer	0	Number of stripes (0 = any)
`exclude`	multiselect (red, maroon, orange, yellow, green, blue, lightblue, white, black)	[]	Colours that are NOT in the flag
`region`	select (world, africa, asia, europe, north-america, south-america, oceania)	"world"	Region
`onlyColours`	boolean	false	Only these colours (penalise flags with more colours)
`limit`	integer	12	Results

Example request

Red, white and blue in three vertical stripes

curl -X POST https://cartographflagfinder.usefulweb.site/api/v1/calculate -H 'content-type: application/json' -d '{"colours":["red","white","blue"],"features":["vstripes"],"bands":3}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://cartographflagfinder.usefulweb.site/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: cartograph_flag_finder
Local stdio connector: node src/mcp-stdio.ts --tool=cartograph-flag-finder

{
  "mcpServers": {
    "cartograph-flag-finder": { "type": "http", "url": "https://cartographflagfinder.usefulweb.site/mcp" }
  }
}