@apifreaks/openapi-specs 0.1.0

package/specs/geodb/countries.json

@@ -0,0 +1,276 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Countries API - Retrieve Global Countries Data",
+    "version": "1.0.0",
+    "description": "Retrieve a complete list of 250 countries and territories with ISO codes (alpha-2, alpha-3, numeric), capital cities, and geographic region/subregion assignments. Optionally filter by region or subregion name to narrow results. Each country object includes the full English name, ISO codes, numeric code, capital city, region, and subregion. Returns all countries by default when no filters are applied. capital, region, and subregion are empty strings (not omitted) for a handful of uninhabited or dependent territories with no assigned value, e.g. Bouvet Island and Heard Island and McDonald Islands have no region/subregion at all, and Antarctica/Tokelau/US Minor Outlying Islands have no capital.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Countries API Server"
+    }
+  ],
+  "paths": {
+    "/geo/countries": {
+      "get": {
+        "tags": ["GeoDB APIs"],
+        "summary": "Retrieve a list of countries with optional region or subregion filtering",
+        "description": "Returns all countries with their ISO codes, capital cities, regions, and subregions. Optional region and subregion parameters narrow results.",
+        "operationId": "getCountries",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "region",
+            "in": "query",
+            "required": false,
+            "description": "Optional filter to return countries within a specific region (e.g., Europe, Asia).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "subregion",
+            "in": "query",
+            "required": false,
+            "description": "Optional filter to return countries within a specific subregion (e.g., Northern Europe, Southern Asia).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with list of countries",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CountriesResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "countries": [
+                        {
+                          "name": "United Kingdom",
+                          "iso_alpha_2": "GB",
+                          "iso_alpha_3": "GBR",
+                          "iso_numeric": 826,
+                          "capital": "London",
+                          "region": "Europe",
+                          "subregion": "Northern Europe"
+                        },
+                        {
+                          "name": "France",
+                          "iso_alpha_2": "FR",
+                          "iso_alpha_3": "FRA",
+                          "iso_numeric": 250,
+                          "capital": "Paris",
+                          "region": "Europe",
+                          "subregion": "Western Europe"
+                        },
+                        {
+                          "name": "Germany",
+                          "iso_alpha_2": "DE",
+                          "iso_alpha_3": "DEU",
+                          "iso_numeric": 276,
+                          "capital": "Berlin",
+                          "region": "Europe",
+                          "subregion": "Western Europe"
+                        }
+                      ]
+                    }
+                  },
+                  "unassignedFields": {
+                    "summary": "Uninhabited/dependent territories — capital, region, and/or subregion come back as empty strings",
+                    "value": {
+                      "countries": [
+                        {
+                          "name": "Bouvet Island",
+                          "iso_alpha_2": "BV",
+                          "iso_alpha_3": "BVT",
+                          "iso_numeric": 74,
+                          "capital": "",
+                          "region": "",
+                          "subregion": ""
+                        },
+                        {
+                          "name": "Antarctica",
+                          "iso_alpha_2": "AQ",
+                          "iso_alpha_3": "ATA",
+                          "iso_numeric": 10,
+                          "capital": "",
+                          "region": "Polar",
+                          "subregion": ""
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Invalid region or subregion name",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "InvalidRegionName": {
+                    "summary": "Invalid region name",
+                    "value": {
+                      "timestamp": "2026-07-24T10:51:01.695Z",
+                      "path": "/v1/countries",
+                      "status": 400,
+                      "error": "Invalid Region Name provided",
+                      "message": "Please provide a valid region name."
+                    }
+                  },
+                  "InvalidSubregionName": {
+                    "summary": "Invalid subregion name",
+                    "value": {
+                      "timestamp": "2026-07-24T10:51:02.247Z",
+                      "path": "/v1/countries",
+                      "status": 400,
+                      "error": "Invalid Subregion Name provided",
+                      "message": "Please provide a valid subregion name."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "CountriesResponse": {
+        "type": "object",
+        "description": "Response containing the list of countries matching the applied region/subregion filters (or all 250 when unfiltered).",
+        "required": ["countries"],
+        "properties": {
+          "countries": {
+            "type": "array",
+            "description": "An array of country objects matching the applied filters.",
+            "items": {
+              "$ref": "#/components/schemas/CountryItem"
+            }
+          }
+        }
+      },
+      "CountryItem": {
+        "type": "object",
+        "description": "A country object containing ISO codes, capital, and region information.",
+        "required": [
+          "name",
+          "iso_alpha_2",
+          "iso_alpha_3",
+          "iso_numeric",
+          "capital",
+          "region",
+          "subregion"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "The full English name of the country."
+          },
+          "iso_alpha_2": {
+            "type": "string",
+            "description": "The ISO 3166-1 alpha-2 two-letter country code."
+          },
+          "iso_alpha_3": {
+            "type": "string",
+            "description": "The ISO 3166-1 alpha-3 three-letter country code."
+          },
+          "iso_numeric": {
+            "type": "integer",
+            "description": "The ISO 3166-1 numeric country code."
+          },
+          "capital": {
+            "type": "string",
+            "description": "The capital city of the country. Empty string for uninhabited/dependent territories with no capital."
+          },
+          "region": {
+            "type": "string",
+            "description": "The broad geographical region the country belongs to. Empty string for a small number of territories with no assigned region."
+          },
+          "subregion": {
+            "type": "string",
+            "description": "The more specific subregion the country belongs to. Empty string for a small number of territories with no assigned subregion."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/geodb/flags-supported.json

@@ -0,0 +1,166 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Supported Flags API Reference",
+    "version": "1.0.0",
+    "description": "Retrieve the list of all country and international organization flags supported by the Flags API. Returns two arrays: `supported_countries` (238 entries) with country names and ISO codes for every available country flag, and `supported_organizations` (22 entries) with case-sensitive identifiers for international organization flags (e.g., United_Nations, NATO, European_Union). Use the returned identifiers with the Flags API's name parameter to retrieve actual flag images — organization identifiers must be passed exactly as listed here, including underscores and capitalization. This endpoint takes no required parameters and has no documented error responses.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Supported Flags API Server"
+    }
+  ],
+  "paths": {
+    "/flags/supported": {
+      "get": {
+        "tags": ["Flags APIs"],
+        "summary": "Retrieve list of all supported flags",
+        "description": "Returns a list of all supported country and international organization flags with their metadata.",
+        "operationId": "getSupportedFlags",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with list of supported flags",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SupportedFlagsResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "supported_countries": [
+                        {
+                          "name": "Luxembourg",
+                          "iso2": "LU",
+                          "iso3": "LUX"
+                        },
+                        {
+                          "name": "Suriname",
+                          "iso2": "SR",
+                          "iso3": "SUR"
+                        },
+                        {
+                          "name": "Tunisia",
+                          "iso2": "TN",
+                          "iso3": "TUN"
+                        },
+                        {
+                          "name": "Colombia",
+                          "iso2": "CO",
+                          "iso3": "COL"
+                        },
+                        {
+                          "name": "Pakistan",
+                          "iso2": "PK",
+                          "iso3": "PAK"
+                        }
+                      ],
+                      "supported_organizations": [
+                        "Commonwealth_of_Independent_States",
+                        "Gulf_Cooperation_Council",
+                        "Arab_League",
+                        "Organization_of_American_States",
+                        "African_Union",
+                        "European_Union",
+                        "United_Nations",
+                        "NATO",
+                        "Association_of_Southeast_Asian_Nations",
+                        "Commonwealth_of_Nations"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "SupportedFlagsResponse": {
+        "type": "object",
+        "description": "The full list of country and organization flag identifiers supported by the Flags API.",
+        "required": ["supported_countries", "supported_organizations"],
+        "properties": {
+          "supported_countries": {
+            "type": "array",
+            "description": "List of all supported country flags with their ISO codes and names.",
+            "items": {
+              "$ref": "#/components/schemas/SupportedCountry"
+            }
+          },
+          "supported_organizations": {
+            "type": "array",
+            "description": "List of all supported international organization flag identifiers.",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "SupportedCountry": {
+        "type": "object",
+        "description": "A supported country with ISO codes.",
+        "required": ["name", "iso2", "iso3"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Full name of the country."
+          },
+          "iso2": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 code."
+          },
+          "iso3": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-3 code."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/geodb/flags.json

@@ -0,0 +1,227 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "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.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Flags API Server"
+    }
+  ],
+  "paths": {
+    "/flags": {
+      "get": {
+        "tags": ["Flags APIs"],
+        "summary": "Retrieve a country or organization flag image",
+        "description": "Returns a flag image for a specified country or international organization. Supports PNG, WEBP, and SVG formats with flat or round shapes.",
+        "operationId": "getFlag",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "query",
+            "required": true,
+            "description": "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.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "type",
+            "in": "query",
+            "required": true,
+            "description": "Type of flag to retrieve. Possible values: country, organization.",
+            "schema": {
+              "type": "string",
+              "enum": ["country", "organization"]
+            }
+          },
+          {
+            "name": "shape",
+            "in": "query",
+            "required": true,
+            "description": "Shape of the flag image. Possible values: flat, round.",
+            "schema": {
+              "type": "string",
+              "enum": ["flat", "round"]
+            }
+          },
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Image format. Possible values: png, webp, svg. Default: png.",
+            "schema": {
+              "type": "string",
+              "enum": ["png", "webp", "svg"],
+              "default": "png"
+            }
+          },
+          {
+            "name": "size",
+            "in": "query",
+            "required": false,
+            "description": "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.",
+            "schema": {
+              "type": "string",
+              "enum": ["16px", "24px", "32px", "48px", "64px"]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with the flag image as raw binary data (not JSON) in the format requested",
+            "content": {
+              "image/png": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResponseSchemas"
+                }
+              },
+              "image/webp": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResponseSchemas"
+                }
+              },
+              "image/svg+xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResponseSchemas"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing required parameter, or type/shape/format/size is not one of the allowed enum values",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingParams": {
+                    "summary": "Missing required name, type, or shape parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/flags",
+                      "status": 400,
+                      "timestamp": "2026-07-24T11:04:56.443Z"
+                    }
+                  },
+                  "InvalidType": {
+                    "summary": "type is not country or organization",
+                    "value": {
+                      "timestamp": "2026-07-24T11:04:56.981953+00:00",
+                      "path": "/flags",
+                      "status": 400,
+                      "error": "Bad Request",
+                      "message": "Invalid type"
+                    }
+                  },
+                  "InvalidShape": {
+                    "summary": "shape is not flat or round",
+                    "value": {
+                      "timestamp": "2026-07-24T11:04:57.507529+00:00",
+                      "path": "/flags",
+                      "status": 400,
+                      "error": "Bad Request",
+                      "message": "Invalid shape"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — Country code or organization identifier not recognized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "InvalidCountryCode": {
+                    "summary": "Invalid country name or code",
+                    "value": {
+                      "timestamp": "2026-07-24T11:04:58.077767+00:00",
+                      "path": "/flags",
+                      "status": 404,
+                      "error": "Not Found",
+                      "message": "Invalid country name or code: ZZ"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "ApiResponseSchemas": {
+        "type": "string",
+        "format": "binary",
+        "title": "Flag Image Response",
+        "description": "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": {
+        "type": "object",
+        "description": "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.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}