--- title: Flags API - Country & Organization Flags in Multiple Formats, Shapes, or Sizes version: 1.0.0 description: Retrieve country and international organization flag images in PNG, WEBP, or SVG format. Supports flat and round shapes in five sizes (16px to 64px, PNG/WEBP only — size is ignored for SVG). Requires a country code or organization identifier, the flag type (country or organization), and the shape (flat or round). Organization identifiers are case-sensitive and must exactly match an entry from the Supported Flags endpoint (e.g. NATO, European_Union, United_Nations) — lowercase or abbreviated forms are not recognized. Optional format (png, webp, svg) and size parameters control the output. Missing/invalid parameter values return a 400 error; unrecognized country or organization identifiers return a 404. On success the response body is the raw binary image, not JSON. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0 paths: 1 operations: 1 schemas: 2 --- ## Table of Contents - [Flags API - Country & Organization Flags in Multiple Formats, Shapes, or Sizes v1.0.0](#flags-api-country-organization-flags-in-multiple-formats-shapes-or-sizes-v100) - [Authentication](#authentication) - [Flags APIs](#flags-apis) - [getFlag](#getflag) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [ApiResponseSchemas](#apiresponseschemas) - [ErrorResponse](#errorresponse) # Flags API - Country & Organization Flags in Multiple Formats, Shapes, or Sizes v1.0.0 Retrieve country and international organization flag images in PNG, WEBP, or SVG format. Supports flat and round shapes in five sizes (16px to 64px, PNG/WEBP only — size is ignored for SVG). Requires a country code or organization identifier, the flag type (country or organization), and the shape (flat or round). Organization identifiers are case-sensitive and must exactly match an entry from the Supported Flags endpoint (e.g. NATO, European_Union, United_Nations) — lowercase or abbreviated forms are not recognized. Optional format (png, webp, svg) and size parameters control the output. Missing/invalid parameter values return a 400 error; unrecognized country or organization identifiers return a 404. On success the response body is the raw binary image, not JSON. Base URLs: * [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0) ## Authentication * API Key (ApiKeyAuthHeader) - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header. * API Key (ApiKeyAuthQuery) - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter. ## Flags APIs ### getFlag `GET /flags` *Retrieve a country or organization flag image* Returns a flag image for a specified country or international organization. Supports PNG, WEBP, and SVG formats with flat or round shapes. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |name|query|string|true|Country code in ISO 3166-1 alpha-2 format for country flags, or organization identifier for organization flags. Organization identifiers are case-sensitive and must exactly match an entry from the Supported Flags endpoint (e.g. NATO, European_Union) — lowercase or abbreviated forms return a 404.| |type|query|string|true|Type of flag to retrieve. Possible values: country, organization.| |shape|query|string|true|Shape of the flag image. Possible values: flat, round.| |format|query|string|false|Image format. Possible values: png, webp, svg. Default: png.| |size|query|string|false|Size of the flag image in pixels. Possible values: 16px, 24px, 32px, 48px, 64px. Default is 64px when omitted. Applies to PNG and WEBP formats only; silently ignored (no error) when format is svg, since SVG is vector-scalable.| ##### Enumerated Values |Parameter|Value| |---|---| |type|country| |type|organization| |shape|flat| |shape|round| |format|png| |format|webp| |format|svg| |size|16px| |size|24px| |size|32px| |size|48px| |size|64px| > Example responses > 200 Response ```xml string ``` > Bad Request — Missing required parameter, or type/shape/format/size is not one of the allowed enum values ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v1.0/flags", "status": 400, "timestamp": "2026-07-24T11:04:56.443Z" } ``` ```json { "timestamp": "2026-07-24T11:04:56.981953+00:00", "path": "/flags", "status": 400, "error": "Bad Request", "message": "Invalid type" } ``` ```json { "timestamp": "2026-07-24T11:04:57.507529+00:00", "path": "/flags", "status": 400, "error": "Bad Request", "message": "Invalid shape" } ``` > Not Found — Country code or organization identifier not recognized ```json { "timestamp": "2026-07-24T11:04:58.077767+00:00", "path": "/flags", "status": 404, "error": "Not Found", "message": "Invalid country name or code: ZZ" } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with the flag image as raw binary data (not JSON) in the format requested|[ApiResponseSchemas](#apiresponseschemas)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing required parameter, or type/shape/format/size is not one of the allowed enum values|[ErrorResponse](#errorresponse)| |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — Country code or organization identifier not recognized|[ErrorResponse](#errorresponse)| #### Response Headers |Status|Header|Type|Format|Description| |---|---|---|---|---| |200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| To perform this operation, you must be authenticated by means of one of the following methods: ApiKeyAuthHeader, ApiKeyAuthQuery ## Schemas ### ApiResponseSchemas Flag Image Response #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |Flag Image Response|string(binary)|false|none|The flag image returned as raw binary data in the requested format (not JSON). Content-Type is one of image/png, image/webp, or image/svg+xml depending on the format parameter.| ### ErrorResponse Standard error envelope returned by the API on failed requests. path and timestamp formatting differ between the missing-parameter case (versioned path, Z-suffixed timestamp) and the invalid-value/not-found cases (unversioned path, offset timestamp with microseconds), since this endpoint is served by a different backend than most of the API. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |error|string|false|none|Short error category or exception type.| |message|string|true|none|Human-readable error message describing the failure.| |path|string|false|none|API endpoint path that produced the error.| |status|integer|false|none|HTTP status code returned with the error.| |timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|