@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/currency/currency-symbols.yaml

@@ -0,0 +1,115 @@
+openapi: 3.1.1
+info:
+  title: Currency Symbols API Reference
+  version: 1.0.0
+  description: Retrieve the complete map of all supported currency codes to their full names. Returns an object where each key is a currency code (USD, EUR, GBP, PKR, BTC, XAU, etc.) and the value is the corresponding currency name. Covers fiat currencies, cryptocurrencies, and precious metals.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Symbols API Server
+paths:
+  /currency/symbols:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get all currency symbols
+      description: Returns a map of currency codes to their full names.
+      operationId: getCurrencySymbols
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CurrencySymbolsResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    currencySymbols:
+                      USD: US Dollar
+                      EUR: Euro
+                      GBP: British Pound Sterling
+                      PKR: Pakistani Rupee
+                      BTC: Bitcoin
+                      XAU: Gold (troy ounce)
+        '406':
+          description: Unsupported Media Type — format is not json or xml
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                badFormat:
+                  summary: format value not supported
+                  value:
+                    error: Unsupported Media Type
+                    message: The media type specified in the request is not supported. For more details, please refer to the API documentation.
+                    path: /v1.0/currency/symbols
+                    status: 406
+                    timestamp: '2026-07-27T12:13:24.369Z'
+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:
+    CurrencySymbolsResponse:
+      type: object
+      required:
+        - currencySymbols
+      properties:
+        currencySymbols:
+          type: object
+          description: Map of currency codes to their full names. Each key is a currency code and the value is the currency name string.
+          additionalProperties:
+            title: CurrencySymbolName
+            type: string
+            description: Full name of the currency (e.g., US Dollar, Euro).
+      description: Currency symbols response containing the map of all currency codes to their names.
+    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/dist/specs/currency/currency-time-series.yaml

@@ -0,0 +1,232 @@
+openapi: 3.1.1
+info:
+  title: Currency Time Series - Historical Currency Exchange Rates for a Time Interval
+  version: 1.0.0
+  description: Retrieve day-by-day historical exchange rates for any base currency over a custom date range up to 1 year. Returns an array of daily rate objects, each containing the date and a map of currency codes to exchange rate strings. Accepts optional target symbols and a base currency (defaults to USD). Returns a 400 error for invalid dates or range exceeded, and a 404 error when no data is available.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Time Series API Server
+paths:
+  /currency/time-series:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get time series of exchange rates
+      description: Returns day-by-day historical exchange rates for a custom date range.
+      operationId: getTimeSeries
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+        - name: startDate
+          in: query
+          required: true
+          description: Start date in `YYYY-MM-DD` format.
+          schema:
+            type: string
+        - name: endDate
+          in: query
+          required: false
+          description: End date in `YYYY-MM-DD` format. Defaults to yesterday.
+          schema:
+            type: string
+        - name: base
+          in: query
+          required: false
+          description: Base currency code. Defaults to `USD`.
+          schema:
+            type: string
+            default: USD
+        - name: symbols
+          in: query
+          required: false
+          description: Comma-separated currency codes. Omit to get all available rates.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CurrencyTimeseriesResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    startDate: '2025-01-01'
+                    endDate: '2025-01-07'
+                    base: USD
+                    historicalRatesList:
+                      - date: '2025-01-01'
+                        rates:
+                          EUR: '0.96605'
+                          PKR: '278.4'
+                      - date: '2025-01-02'
+                        rates:
+                          EUR: '0.9739'
+                          PKR: '278.4'
+                      - date: '2025-01-03'
+                        rates:
+                          EUR: '0.97005'
+                          PKR: '278.4'
+                      - date: '2025-01-04'
+                        rates:
+                          EUR: '0.97005'
+                          PKR: '278.4'
+                      - date: '2025-01-05'
+                        rates:
+                          EUR: '0.9704'
+                          PKR: '278.4'
+                      - date: '2025-01-06'
+                        rates:
+                          EUR: '0.96305'
+                          PKR: '278.4'
+                      - date: '2025-01-07'
+                        rates:
+                          EUR: '0.967'
+                          PKR: '278.4'
+        '400':
+          description: Bad request - Invalid dates or range exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                missingStartDate:
+                  summary: Missing required startDate parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/currency/time-series
+                    status: 400
+                    timestamp: '2026-07-27T12:08:01.002Z'
+                rangeExceeded:
+                  summary: Interval exceeds 1 year
+                  value:
+                    timestamp: 1785154081486
+                    status: 400
+                    error: Invalid Param Exception
+                    message: You can only retrieve time series data for a maximum interval of 1 Year
+                    path: /v2.0/timeseries
+                startAfterEnd:
+                  summary: startDate is after endDate or the current date (includes any future date)
+                  value:
+                    timestamp: 1785154082031
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Starting date cannot be after current date or ending date.
+                    path: /v2.0/timeseries
+                invalidDateFormat:
+                  summary: startDate/endDate not in YYYY-MM-DD format
+                  value:
+                    timestamp: 1785154106063
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Provided Dates are in Invalid Format. Dates must be in a valid format YYYY-MM-DD!
+                    path: /v2.0/timeseries
+        '404':
+          description: Not found - No data for interval
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                noData:
+                  summary: base or symbols not supported for the given interval
+                  value:
+                    timestamp: 1785154125982
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided base and symbols are not found for given intervals.
+                    path: /v2.0/timeseries
+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:
+    CurrencyTimeseriesResponse:
+      type: object
+      required:
+        - startDate
+        - endDate
+        - base
+        - historicalRatesList
+      properties:
+        startDate:
+          type: string
+          description: Start date of the interval (YYYY-MM-DD).
+        endDate:
+          type: string
+          description: End date of the interval (YYYY-MM-DD).
+        base:
+          type: string
+          description: Base currency used for all rates in the series.
+        historicalRatesList:
+          type: array
+          description: Array of daily rate objects within the specified interval.
+          items:
+            $ref: '#/components/schemas/CurrencyTimeSeriesItem'
+      description: Currency time series response containing daily exchange rate data over a date range.
+    CurrencyTimeSeriesItem:
+      type: object
+      description: Daily exchange rate data for a specific date.
+      required:
+        - date
+        - rates
+      properties:
+        date:
+          type: string
+          description: Date within the interval (YYYY-MM-DD).
+        rates:
+          type: object
+          description: Map of currency codes to exchange rate strings for that date. Each key is a currency code and the value is an exchange rate string.
+          additionalProperties:
+            title: ExchangeRateString
+            type: string
+            description: Exchange rate value as a string for this currency code.
+    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, 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/dist/specs/currency/geolocalized-currency-conversion.yaml

@@ -0,0 +1,214 @@
+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: []