@apifreaks/openapi-specs 0.1.0

package/specs/currency/geolocalized-currency-conversion.json

@@ -0,0 +1,287 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "IP Currency API - Convert Any Amount to Local Currency from an IP Address",
+    "version": "1.0.0",
+    "description": "Convert an amount from one currency to the local currency of a given IP address using the latest exchange rates. Uses IP geolocation to determine the target currency based on the visitor country. Accepts source currency, IP address, and amount. Supports fiat, crypto, and metals. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Geolocalized Currency Converter API Server"
+    }
+  ],
+  "paths": {
+    "/currency/converter/ip-to-currency": {
+      "get": {
+        "tags": ["Currency APIs"],
+        "summary": "Convert currency based on IP geolocation",
+        "description": "Converts an amount to the local currency of a given IP address.",
+        "operationId": "convertByIp",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format: `json` (default) or `xml`.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "from",
+            "in": "query",
+            "required": true,
+            "description": "Source currency code.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "ip",
+            "in": "query",
+            "required": false,
+            "description": "IPv4 or IPv6 address. Defaults to the request IP.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "amount",
+            "in": "query",
+            "required": false,
+            "description": "Amount to convert, as a decimal. Defaults to `1`. Non-numeric values return a 400.",
+            "schema": {
+              "type": "string",
+              "default": "1"
+            }
+          },
+          {
+            "name": "updates",
+            "in": "query",
+            "required": false,
+            "description": "Update frequency: `1m` (default), `10m`, `1h`, or `1d`.",
+            "schema": {
+              "type": "string",
+              "enum": ["1m", "10m", "1h", "1d"],
+              "default": "1m"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeolocalizedCurrencyConverterResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "date": "2026-07-27 12:10:00+00",
+                      "from": "USD",
+                      "to": "PKR",
+                      "rate": "277.863",
+                      "ipAddress": "182.186.18.91",
+                      "givenAmount": "100.0",
+                      "convertedAmount": "27786.300"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - Invalid IP, amount, or updates",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingFrom": {
+                    "summary": "Missing required from parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/currency/converter/ip-to-currency",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:10:31.824Z"
+                    }
+                  },
+                  "invalidAmount": {
+                    "summary": "amount is not numeric",
+                    "value": {
+                      "timestamp": 1785154232373,
+                      "status": 400,
+                      "error": "Method Argument Type Mismatch",
+                      "message": "Invalid Amount. Please provide amount in decimal format and greater than 0!",
+                      "path": "/v2.0/iptocurrency"
+                    }
+                  },
+                  "invalidIp": {
+                    "summary": "ip is not a valid IPv4/IPv6 address",
+                    "value": {
+                      "timestamp": 1785154232944,
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Provided IP Address not-an-ip is invalid.",
+                      "path": "/v2.0/iptocurrency"
+                    }
+                  },
+                  "invalidUpdates": {
+                    "summary": "updates is not one of 1m/10m/1h/1d",
+                    "value": {
+                      "timestamp": 1785154262483,
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Please provide valid updates parameter (1d,1h,10m,1m)",
+                      "path": "/v2.0/iptocurrency"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - IP geolocation or currency not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "unknownIp": {
+                    "summary": "IP could not be geolocated",
+                    "value": {
+                      "timestamp": 1785154233555,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Geolocation of provided IP 0.0.0.0 is unknown.",
+                      "path": "/v2.0/iptocurrency"
+                    }
+                  },
+                  "invalidBase": {
+                    "summary": "from currency not supported",
+                    "value": {
+                      "timestamp": 1785154234101,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided currency ZZZ are not available in our database!",
+                      "path": "/v2.0/iptocurrency"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "GeolocalizedCurrencyConverterResponse": {
+        "type": "object",
+        "required": [
+          "date",
+          "from",
+          "to",
+          "rate",
+          "ipAddress",
+          "givenAmount",
+          "convertedAmount"
+        ],
+        "properties": {
+          "date": {
+            "type": "string",
+            "description": "Date and time with timezone (UTC) when the rate was recorded."
+          },
+          "from": {
+            "type": "string",
+            "description": "Source currency code."
+          },
+          "to": {
+            "type": "string",
+            "description": "Target currency code — the local currency of the IP."
+          },
+          "rate": {
+            "type": "string",
+            "description": "Exchange rate from source to target currency."
+          },
+          "ipAddress": {
+            "type": "string",
+            "description": "IP address used for geolocation."
+          },
+          "givenAmount": {
+            "type": "string",
+            "description": "Amount provided for conversion."
+          },
+          "convertedAmount": {
+            "type": "string",
+            "description": "Converted amount in the target (local) currency."
+          }
+        },
+        "description": "Geolocalized currency conversion response containing the rate and converted amount based on IP geolocation."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors use a Unix millisecond timestamp and an internal service path instead.",
+        "required": ["message"],
+        "properties": {
+          "timestamp": {
+            "type": ["string", "integer"],
+            "description": "Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "error": {
+            "type": "string",
+            "description": "Specific error type (e.g., Invalid Param Exception, Method Argument Type Mismatch, Not Found Exception)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/currency/historical-currency-converter.json

@@ -0,0 +1,269 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Historical Currency Converter API Reference",
+    "version": "1.0.0",
+    "description": "Convert an amount from one currency to another using exchange rates from a specific historical date. Supports fiat, crypto, and metals. Returns the date, source and target currencies, the historical rate, and the converted amount. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Historical Currency Converter API Server"
+    }
+  ],
+  "paths": {
+    "/currency/converter/historical/prices": {
+      "get": {
+        "tags": ["Currency APIs"],
+        "summary": "Convert currency with historical rates",
+        "description": "Converts an amount using exchange rates from a specific historical date.",
+        "operationId": "convertHistorical",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format: `json` (default) or `xml`.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "from",
+            "in": "query",
+            "required": true,
+            "description": "Source currency code.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "in": "query",
+            "required": true,
+            "description": "Target currency code.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "amount",
+            "in": "query",
+            "required": false,
+            "description": "Amount to convert, as a decimal. Defaults to `1`. Must be numeric — non-numeric values return a 400 (negative values are accepted despite the error message's wording).",
+            "schema": {
+              "type": "string",
+              "default": "1"
+            }
+          },
+          {
+            "name": "date",
+            "in": "query",
+            "required": true,
+            "description": "Historical date in `YYYY-MM-DD` format.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HistoricalCurrencyConverterResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "date": "2025-01-10",
+                      "from": "USD",
+                      "to": "EUR",
+                      "rate": "0.97620",
+                      "givenAmount": "100.0",
+                      "convertedAmount": "97.620"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - Invalid amount or date format",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingParams": {
+                    "summary": "Missing required from/to/date parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/currency/converter/historical/prices",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:07:03.772Z"
+                    }
+                  },
+                  "invalidAmount": {
+                    "summary": "amount is not numeric",
+                    "value": {
+                      "timestamp": 1785154024296,
+                      "status": 400,
+                      "error": "Method Argument Type Mismatch",
+                      "message": "Invalid Amount. Please provide amount in decimal format and greater than 0!",
+                      "path": "/v2.0/convert/historical"
+                    }
+                  },
+                  "invalidDateFormat": {
+                    "summary": "date is not in YYYY-MM-DD format",
+                    "value": {
+                      "timestamp": 1785154024931,
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Provided Date 10-01-2025 is in invalid format. It should be like  YYYY-MM-DD!",
+                      "path": "/v2.0/convert/historical"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - Currency or date not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "dateNotFound": {
+                    "summary": "No data for the given date",
+                    "value": {
+                      "timestamp": 1785154025547,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided date 2099-01-01 are not available in our database.",
+                      "path": "/v2.0/convert/historical"
+                    }
+                  },
+                  "invalidBase": {
+                    "summary": "from currency not supported",
+                    "value": {
+                      "timestamp": 1785154026188,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided currency ZZZ are not available in our database!",
+                      "path": "/v2.0/convert/historical"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "HistoricalCurrencyConverterResponse": {
+        "type": "object",
+        "required": [
+          "date",
+          "from",
+          "to",
+          "rate",
+          "givenAmount",
+          "convertedAmount"
+        ],
+        "properties": {
+          "date": {
+            "type": "string",
+            "description": "Date and time with timezone (UTC) when the rate was recorded."
+          },
+          "from": {
+            "type": "string",
+            "description": "Source currency code."
+          },
+          "to": {
+            "type": "string",
+            "description": "Target currency code."
+          },
+          "rate": {
+            "type": "string",
+            "description": "Conversion rate from source to target currency."
+          },
+          "givenAmount": {
+            "type": "string",
+            "description": "The amount provided for conversion."
+          },
+          "convertedAmount": {
+            "type": "string",
+            "description": "The converted amount in the target currency."
+          }
+        },
+        "description": "Historical currency conversion response containing the historical rate and converted amount."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors use a Unix millisecond timestamp and an internal service path instead.",
+        "required": ["message"],
+        "properties": {
+          "timestamp": {
+            "type": ["string", "integer"],
+            "description": "Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "error": {
+            "type": "string",
+            "description": "Specific error type (e.g., Invalid Param Exception, Method Argument Type Mismatch, Not Found Exception)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}