{"openapi":"3.1.0","info":{"title":"Countries API","version":"1.0.0","description":"Read-only REST Countries–style JSON API with build-time Wikidata enrichment (population, economics, development, government, company heuristics, computed metrics) and a flag CDN. No API keys. When x402 is enabled on a deployment, GET /v1 data routes require an HTTP 402 micropayment (PAYMENT-SIGNATURE); GET /v1/notice stays free. List pages return at most 5 countries."},"servers":[{"url":"https://api.reqi.dev","description":"API host"},{"url":"https://cdn.reqi.dev","description":"Flag CDN"}],"tags":[{"name":"Countries","description":"JSON country records under /v1"},{"name":"Meta","description":"Production baseline and discovery"},{"name":"Flags","description":"PNG and SVG redirects"}],"paths":{"/v1/notice":{"get":{"operationId":"getV1Notice","summary":"Production API notice","description":"JSON summary of the shipped production surface: hosts, site routes, /v1 routes, pagination, flags, and data sources. Not gated by x402.","tags":["Meta"],"responses":{"200":{"description":"Production baseline notice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ProductionNotice"}}}}}}},"/v1":{"get":{"operationId":"listCountries","summary":"List countries","description":"Paginated list in dataset order, or random modes via the page query. Max 5 items.","tags":["Countries"],"parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/index"},{"$ref":"#/components/parameters/seed"}],"responses":{"200":{"$ref":"#/components/responses/CountryList"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/v1/list":{"get":{"operationId":"listCountriesAlias","summary":"List countries (alias)","description":"Same as GET /v1.","tags":["Countries"],"parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/index"},{"$ref":"#/components/parameters/seed"}],"responses":{"200":{"$ref":"#/components/responses/CountryList"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/v1/random":{"get":{"operationId":"randomCountry","summary":"Random country","description":"Returns one random country as a one-element array, subject to offset/limit.","tags":["Countries"],"parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/current":{"get":{"operationId":"getCurrentCountry","summary":"Caller’s country","description":"Returns one country object inferred from the request IP via edge geo headers (for example x-vercel-ip-country on Vercel). Response header X-Request-Country is the detected ISO 3166-1 alpha-2 code. Supports fields projection only (no limit/offset).","tags":["Countries"],"parameters":[{"$ref":"#/components/parameters/fields"}],"responses":{"200":{"description":"Projected country object for the detected location.","headers":{"X-Request-Country":{"description":"Detected ISO 3166-1 alpha-2 country code.","schema":{"type":"string","pattern":"^[A-Z]{2}$"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Country"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/alpha/{codes}":{"get":{"operationId":"getByAlpha","summary":"Filter by ISO codes","description":"Match cca2, cca3, or ccn3. Multiple codes are comma-separated.","tags":["Countries"],"parameters":[{"name":"codes","in":"path","required":true,"description":"Comma-separated ISO alpha-2, alpha-3, or numeric codes.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/name/{name}":{"get":{"operationId":"getByName","summary":"Search by name","description":"Substring match on country names unless fullText=true.","tags":["Countries"],"parameters":[{"name":"name","in":"path","required":true,"description":"Country name.","schema":{"type":"string"}},{"name":"fullText","in":"query","description":"If true, require an exact common or official name match.","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/capital/{capital}":{"get":{"operationId":"getByCapital","summary":"Filter by capital","description":"Match capital city names.","tags":["Countries"],"parameters":[{"name":"capital","in":"path","required":true,"description":"Capital city name.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/region/{region}":{"get":{"operationId":"getByRegion","summary":"Filter by region","description":"Match the region field.","tags":["Countries"],"parameters":[{"name":"region","in":"path","required":true,"description":"Region name, for example Europe.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/subregion/{subregion}":{"get":{"operationId":"getBySubregion","summary":"Filter by subregion","description":"Match the subregion field.","tags":["Countries"],"parameters":[{"name":"subregion","in":"path","required":true,"description":"Subregion name.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/lang/{lang}":{"get":{"operationId":"getByLanguage","summary":"Filter by language","description":"Match an ISO 639 language key on the country.","tags":["Countries"],"parameters":[{"name":"lang","in":"path","required":true,"description":"ISO 639 language code.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/currency/{currency}":{"get":{"operationId":"getByCurrency","summary":"Filter by currency","description":"Match an ISO 4217 currency code.","tags":["Countries"],"parameters":[{"name":"currency","in":"path","required":true,"description":"ISO 4217 currency code, for example eur.","schema":{"type":"string"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/independent":{"get":{"operationId":"getByIndependent","summary":"Filter by independence","description":"Requires status=true or status=false.","tags":["Countries"],"parameters":[{"name":"status","in":"query","required":true,"description":"Independent (true) or not (false).","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/CountryArray"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/get/{code}":{"get":{"operationId":"getFlagPngDefault","summary":"Flag PNG (default)","description":"301 redirect to the hashed PNG.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/get/png/{code}":{"get":{"operationId":"getFlagPng","summary":"Flag PNG","description":"301 redirect to the hashed PNG.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/get/svg/{code}":{"get":{"operationId":"getFlagSvg","summary":"Flag SVG","description":"301 redirect to the hashed SVG.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/flags/get/{code}":{"get":{"operationId":"getFlagPngDefaultOnApi","summary":"Flag PNG on API host","description":"Same as /get/{code}, available on api.reqi.dev.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/flags/get/png/{code}":{"get":{"operationId":"getFlagPngOnApi","summary":"Flag PNG on API host","description":"Same as /get/png/{code}.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/flags/get/svg/{code}":{"get":{"operationId":"getFlagSvgOnApi","summary":"Flag SVG on API host","description":"Same as /get/svg/{code}.","tags":["Flags"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code (case-insensitive).","schema":{"type":"string"}}],"responses":{"301":{"description":"Redirect to /flags/{hash}.png or .svg"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"parameters":{"fields":{"name":"fields","in":"query","description":"Comma-separated field list. Supports dot paths (name.common). Use * or omit for the full object.","schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"Page size from 1 to 5. Default 5.","schema":{"type":"integer","minimum":1,"maximum":5}},"offset":{"name":"offset","in":"query","description":"Number of matches to skip. Default 0. Used when page is omitted.","schema":{"type":"integer","minimum":0}},"page":{"name":"page","in":"query","description":"Zero-based page index, or \"random\" (seeded shuffle) or \"randomized\" (random sample).","schema":{"type":"string"}},"index":{"name":"index","in":"query","description":"Slice index for page=random. Default 0.","schema":{"type":"integer","minimum":0}},"seed":{"name":"seed","in":"query","description":"Shuffle seed for page=random. Generated and returned as X-List-Seed when omitted.","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"integer"}}},"FlagUrls":{"type":"object","required":["svg","png","alt"],"properties":{"svg":{"type":"string","format":"uri"},"png":{"type":"string","format":"uri"},"alt":{"type":"string"}}},"CountryName":{"type":"object","required":["common","official"],"properties":{"common":{"type":"string"},"official":{"type":"string"},"native":{"type":"object","additionalProperties":true}}},"EnrichmentPopulation":{"type":"object","required":["value","source"],"properties":{"value":{"type":"number"},"source":{"type":"string","enum":["wikidata","mledoze"]},"asOf":{"type":"string"}}},"EnrichmentEconomics":{"type":"object","properties":{"gdp":{"type":"number","nullable":true},"gdpPerCapita":{"type":"number","nullable":true},"gdpYear":{"type":"integer","nullable":true}}},"EnrichmentDevelopment":{"type":"object","properties":{"hdi":{"type":"number","nullable":true},"lifeExpectancy":{"type":"number","nullable":true},"gini":{"type":"number","nullable":true}}},"EnrichmentGovernment":{"type":"object","properties":{"type":{"type":"string","nullable":true},"website":{"type":"string","format":"uri","nullable":true}}},"EnrichmentCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true},"wikidataId":{"type":"string","nullable":true},"revenue":{"type":"number","nullable":true},"profit":{"type":"number","nullable":true},"asOf":{"type":"string","nullable":true}}},"EnrichmentComputed":{"type":"object","properties":{"populationDensity":{"type":"number","nullable":true},"capitalPopulationShare":{"type":"number","nullable":true}}},"Enrichment":{"type":"object","required":["fetchedAt"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"population":{"$ref":"#/components/schemas/EnrichmentPopulation"},"economics":{"$ref":"#/components/schemas/EnrichmentEconomics"},"development":{"$ref":"#/components/schemas/EnrichmentDevelopment"},"government":{"$ref":"#/components/schemas/EnrichmentGovernment"},"company":{"oneOf":[{"$ref":"#/components/schemas/EnrichmentCompany"},{"type":"null"}]},"computed":{"$ref":"#/components/schemas/EnrichmentComputed"}}},"V1NoticeRoute":{"type":"object","required":["method","path","description"],"properties":{"method":{"type":"string","enum":["GET"]},"path":{"type":"string"},"description":{"type":"string"}}},"V1ProductionNotice":{"type":"object","required":["schemaVersion","kind","scope","asOf","gitCommit","hosts","site","v1","flags","data","license"],"properties":{"schemaVersion":{"type":"integer","minimum":1,"maximum":1},"kind":{"type":"string","enum":["v1-notice"]},"scope":{"type":"string","enum":["production"]},"asOf":{"type":"string","format":"date-time"},"gitCommit":{"type":"string"},"hosts":{"type":"object","required":["api","flagsCdn"],"properties":{"api":{"type":"string","format":"uri"},"flagsCdn":{"type":"string","format":"uri"}}},"site":{"type":"array","items":{"$ref":"#/components/schemas/V1NoticeRoute"}},"v1":{"type":"object","additionalProperties":true},"flags":{"type":"object","additionalProperties":true},"data":{"type":"array","items":{"type":"string"}},"license":{"type":"string"}}},"Country":{"type":"object","required":["name","cca2","cca3","population","flags"],"properties":{"name":{"$ref":"#/components/schemas/CountryName"},"tld":{"type":"array","items":{"type":"string"}},"cca2":{"type":"string"},"ccn3":{"type":"string"},"cca3":{"type":"string"},"cioc":{"type":"string"},"independent":{"type":"boolean"},"status":{"type":"string"},"unMember":{"type":"boolean"},"unRegionalGroup":{"type":"string"},"wikidataId":{"type":"string"},"currencies":{"type":"object","additionalProperties":true},"capital":{"type":"array","items":{"type":"string"}},"altSpellings":{"type":"array","items":{"type":"string"}},"region":{"type":"string"},"subregion":{"type":"string"},"languages":{"type":"object","additionalProperties":{"type":"string"}},"translations":{"type":"object","additionalProperties":true},"latlng":{"type":"array","items":{"type":"number"}},"landlocked":{"type":"boolean"},"borders":{"type":"array","items":{"type":"string"}},"area":{"type":"number"},"flag":{"type":"string"},"demonyms":{"type":"object","additionalProperties":true},"population":{"type":"number","nullable":true},"capitalInfo":{"type":"object","additionalProperties":true},"enrichment":{"$ref":"#/components/schemas/Enrichment"},"maps":{"type":"object","additionalProperties":true},"fifa":{"type":"string"},"timezones":{"type":"array","items":{"type":"string"}},"continents":{"type":"array","items":{"type":"string"}},"flags":{"$ref":"#/components/schemas/FlagUrls"}}}},"responses":{"CountryArray":{"description":"JSON array of country objects (possibly projected).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}},"CountryList":{"description":"JSON array of country objects.","headers":{"X-List-Page":{"description":"Present for numbered page mode.","schema":{"type":"string"}},"X-List-Pages":{"description":"Present for numbered page and page=random.","schema":{"type":"string"}},"X-List-Seed":{"description":"Present for page=random.","schema":{"type":"string"}},"X-List-Index":{"description":"Present for page=random.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}},"BadRequest":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No matching country or flag asset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Returned when x402 is enabled and the request lacks a valid PAYMENT-SIGNATURE. Response includes PAYMENT-REQUIRED with acceptable payment options.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired payload.","schema":{"type":"string"}}}}}}}