@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/financial/vat-rates-country.yaml

@@ -0,0 +1,212 @@
+openapi: 3.1.1
+info:
+  title: VAT Rates by Country API Reference
+  version: 1.0.0
+  description: Get VAT rates for a specific country including standard, reduced, and super-reduced rates. Covers all EU and major global jurisdictions.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: VAT Rates by Country API Server
+paths:
+  /vat/rates/country:
+    get:
+      tags:
+        - Financial APIs
+      summary: Get VAT rate by country code
+      description: Fetches VAT rates for a single country or state provided via query parameters.
+      operationId: getVatRatesByCountry
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Specify the desired response format. Options: ''json'' (default) or ''xml''.'
+        - name: country
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Country identifier in Alpha-2 (PK), Alpha-3 (PAK), or full name (Pakistan). Combine with the optional "state" query for sub-national VAT; values are case-insensitive and may use underscores instead of spaces.
+        - name: state
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional state or region in Alpha-2 (NY) or full name (New_York). Use with "country" for state-level VAT; values are case-insensitive and may use underscores.
+      responses:
+        '200':
+          description: Successful response with a JSON array containing VAT rate objects for the requested country or state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VatCountryResponse'
+              examples:
+                typicalSuccess:
+                  summary: Country-level VAT rate
+                  value:
+                    - country: DE
+                      type: vat
+                      currency: EUR
+                      standard_rate: 0.19
+                      reduced_rate:
+                        - 0.07
+                        - 0
+                      categories:
+                        books: 0.07
+                        newspapers: 0.07
+                        periodicals: 0.07
+                        broadcasting: 0
+                stateLevel:
+                  summary: State/region-level sales tax rate
+                  value:
+                    - country: US
+                      state: NY
+                      type: vat
+                      currency: ''
+                      standard_rate: 0.04
+        '400':
+          description: Bad Request — Missing required country parameter
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingCountry:
+                  summary: Missing required country parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/vat/rates/country
+                    status: 400
+                    timestamp: '2026-07-27T11:45:34.183Z'
+        '404':
+          description: Not Found — No VAT data for the given country/state
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NotFound:
+                  summary: No VAT data for the given country
+                  value:
+                    message: No VAT data found.
+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:
+    VatCountryResponse:
+      type: array
+      description: Array of VAT rate objects for the requested country or state.
+      items:
+        $ref: '#/components/schemas/VatRateItem'
+    VatRateItem:
+      type: object
+      required:
+        - country
+        - type
+        - currency
+        - standard_rate
+      properties:
+        country:
+          type: string
+          description: Country identifier returned by the API.
+        state:
+          type:
+            - string
+            - 'null'
+          description: State or region identifier for sub-national tax data.
+        type:
+          type: string
+          description: Tax type for the location (e.g., vat or none).
+        currency:
+          type: string
+          description: ISO 4217 currency code for the country or state.
+        standard_rate:
+          type: number
+          format: float
+          description: Standard VAT or sales tax rate as a decimal (e.g., 0.19 = 19%).
+        reduced_rate:
+          type: array
+          items:
+            $ref: '#/components/schemas/VatRateDecimal'
+          description: Reduced VAT rates when the country defines them (EU/UK only).
+        super_reduced_rate:
+          type: array
+          items:
+            $ref: '#/components/schemas/VatRateDecimal'
+          description: Super-reduced VAT rates for eligible categories (EU/UK only).
+        parking_rate:
+          type: number
+          format: float
+          description: Parking rate where defined (EU/UK only).
+        categories:
+          description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country - not every category below applies to every country.
+          $ref: '#/components/schemas/VatCategories'
+      description: Each item in the array represents a VAT rate object for the requested country or state.
+    VatRateDecimal:
+      type: number
+      format: float
+      description: A VAT rate expressed as a decimal (e.g., 0.19 = 19%).
+    VatCategories:
+      type: object
+      description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.
+      properties:
+        books:
+          type: number
+          format: float
+          description: VAT rate for books, as a decimal (e.g., 0.07 = 7%).
+        newspapers:
+          type: number
+          format: float
+          description: VAT rate for newspapers, as a decimal (e.g., 0.07 = 7%).
+        periodicals:
+          type: number
+          format: float
+          description: VAT rate for periodicals, as a decimal (e.g., 0.07 = 7%).
+        broadcasting:
+          type: number
+          format: float
+          description: VAT rate for broadcasting services, as a decimal (e.g., 0.19 = 19%).
+      required: []
+    ErrorResponse:
+      type: object
+      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).
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/general/usage-credits.yaml

@@ -0,0 +1,188 @@
+openapi: 3.1.1
+info:
+  title: Credits Usage API
+  version: 1.0.0
+  description: Retrieve the remaining and consumed API credit balances for the authenticated organization. Returns subscription-plan credits, subscription surcharge (overage) credits, and one-off credit purchases as separate balances, each with allowed and used counts. Only an organization admin API key can call this endpoint; all other keys receive a 403. There are no optional data modules for this endpoint — the response always includes the full credit breakdown.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Credits Usage API Server
+paths:
+  /credits/usage/info:
+    get:
+      tags:
+        - General APIs
+      summary: Get remaining and consumed API credit balances for the organization
+      description: Returns subscription, subscription-surcharge, and one-off credit balances for the authenticated organization's account.
+      operationId: getCreditsUsage
+      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 credit balances
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreditsUsageResponse'
+              examples:
+                success:
+                  summary: Typical response
+                  value:
+                    apiKey: demo
+                    userStatus: active
+                    subActive: true
+                    subStatus: active
+                    subAllowedCredits: 10000
+                    subUsedCredits: 2500
+                    subSurchargeStatus: none
+                    subSurchargeAllowedCredits: 0
+                    subSurchargeUsedCredits: 0
+                    subSurchargeAllowed: false
+                    oneOffCreditsActive: true
+                    oneOffAllowedCredits: 5000
+                    oneOffUsedCredits: 1000
+        '403':
+          description: Forbidden — Caller is not an organization admin
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                notOrgAdmin:
+                  summary: Not an organization admin
+                  value:
+                    timestamp: '2026-07-27T10:23:16.548Z'
+                    path: /v1.0/credits/usage/info
+                    status: 403
+                    error: API Access Exception
+                    message: You need to be organization admin to access this endpoint.
+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:
+    CreditsUsageResponse:
+      type: object
+      description: Credit balances for the organization's subscription, subscription surcharge, and one-off purchases.
+      required:
+        - apiKey
+        - userStatus
+        - oneOffCreditsActive
+        - oneOffAllowedCredits
+        - oneOffUsedCredits
+      properties:
+        apiKey:
+          type: string
+          description: The API key the credit balances belong to.
+        userStatus:
+          type: string
+          enum:
+            - active
+            - inactive
+            - deleted
+          description: Status of the user account.
+        subActive:
+          type:
+            - boolean
+            - 'null'
+          description: Whether a subscription plan is currently active. Null if the account has no subscription.
+        subStatus:
+          type:
+            - string
+            - 'null'
+          enum:
+            - active
+            - overdue
+            - cancelled
+            - deactivated
+            - null
+          description: Status of the subscription credits. Null if the account has no subscription.
+        subAllowedCredits:
+          type:
+            - integer
+            - 'null'
+          description: Total credits allowed under the subscription plan. Null if the account has no subscription.
+        subUsedCredits:
+          type:
+            - integer
+            - 'null'
+          description: Credits consumed under the subscription plan. Null if the account has no subscription.
+        subSurchargeStatus:
+          type:
+            - string
+            - 'null'
+          enum:
+            - none
+            - payment_added
+            - payment_cleared
+            - null
+          description: Status of the subscription surcharge (overage) credits. Null if the account has no subscription.
+        subSurchargeAllowedCredits:
+          type:
+            - integer
+            - 'null'
+          description: Total surcharge credits allowed. Null if the account has no subscription.
+        subSurchargeUsedCredits:
+          type:
+            - integer
+            - 'null'
+          description: Surcharge credits consumed. Null if the account has no subscription.
+        subSurchargeAllowed:
+          type:
+            - boolean
+            - 'null'
+          description: Whether surcharge (overage) usage is allowed on the subscription. Null if the account has no subscription.
+        oneOffCreditsActive:
+          type: boolean
+          description: Whether the account has active one-off (pay-as-you-go) credits.
+        oneOffAllowedCredits:
+          type: integer
+          description: Total one-off credits purchased.
+        oneOffUsedCredits:
+          type: integer
+          description: One-off credits consumed.
+    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/geocoding/forward-geocoding.yaml

@@ -0,0 +1,292 @@
+openapi: 3.1.1
+info:
+  title: Forward Geocoding API - Convert Address to Lat/Long Coordinates
+  version: 1.0.0
+  description: Convert a free-form address, place name, or point of interest into geographic coordinates. Returns up to 40 ranked matches per request, each with latitude/longitude, a structured address breakdown (street, city, state, country), a WGS84 bounding box, and any points of interest at that location. Use the `limit` parameter to control result count, the four `min_lat`/`max_lat`/`min_lon`/`max_lon` parameters together to bias results toward a geographic viewbox, and the `Accept-Language` header to localize result names. A query that matches nothing returns a `404` error rather than an empty array.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Forward Geocoding API Server
+paths:
+  /geocoder/search:
+    get:
+      tags:
+        - Geocoder APIs
+      summary: Convert an address or place name into geographic coordinates
+      description: Search for a free-form address, place name, or point of interest and return matching locations with coordinates, structured address components, and a bounding box.
+      operationId: forwardGeocode
+      parameters:
+        - name: query
+          in: query
+          required: true
+          description: Free-form search query, e.g. `Wembley Stadium, London`.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of results to return. May return fewer if matches are weak.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 40
+            default: 1
+        - name: min_lat
+          in: query
+          required: false
+          description: Minimum latitude of the viewbox used to bias results. Must be provided together with `max_lat`, `min_lon`, and `max_lon`, and must be less than or equal to `max_lat`.
+          schema:
+            type: number
+            format: float
+            minimum: -90
+            maximum: 90
+        - name: max_lat
+          in: query
+          required: false
+          description: Maximum latitude of the viewbox used to bias results. Must be provided together with `min_lat`, `min_lon`, and `max_lon`, and must be greater than or equal to `min_lat`.
+          schema:
+            type: number
+            format: float
+            minimum: -90
+            maximum: 90
+        - name: min_lon
+          in: query
+          required: false
+          description: Minimum longitude of the viewbox used to bias results. Must be provided together with `min_lat`, `max_lat`, and `max_lon`, and must be less than or equal to `max_lon`.
+          schema:
+            type: number
+            format: float
+            minimum: -180
+            maximum: 180
+        - name: max_lon
+          in: query
+          required: false
+          description: Maximum longitude of the viewbox used to bias results. Must be provided together with `min_lat`, `max_lat`, and `min_lon`, and must be greater than or equal to `min_lon`.
+          schema:
+            type: number
+            format: float
+            minimum: -180
+            maximum: 180
+        - name: Accept-Language
+          in: header
+          required: false
+          description: Preferred language order for result names, as a comma-separated list of language codes or a single code. Results are returned in the first matched language, falling back to `en` if none match.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful geocoding response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ForwardGeocodeResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    - lat: 51.55606945
+                      lon: -0.27960339379401444
+                      name: Wembley Stadium
+                      category: tourism
+                      type: attraction
+                      poi:
+                        - name: Wembley Stadium
+                          category: leisure
+                          type: stadium
+                      street: Pacific Crescent
+                      area: London Borough of Brent
+                      postcode: HA9 0SL
+                      city: Greater London
+                      state_code: GB-ENG
+                      state: England
+                      country_code: GB
+                      country: United Kingdom
+                      full_address: Wembley Stadium, Pacific Crescent, London Borough of Brent, Greater London, England, HA9 0SL, United Kingdom
+                      bounding_box:
+                        - '51.5547925'
+                        - '51.5573402'
+                        - '-0.2817245'
+                        - '-0.2774831'
+        '400':
+          description: Bad Request — Invalid or missing parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                missingQuery:
+                  summary: Missing required `query` parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/geocoder/search
+                    status: 400
+                    timestamp: '2026-07-22T14:29:30.362Z'
+                invalidLimit:
+                  summary: '`limit` outside the 1-40 range'
+                  value:
+                    error: Invalid Query Limit Provided
+                    message: Please provide a valid limit. Valid range is from 1 to 40.
+                    path: /v1.0/geocoder/search
+                    status: 400
+                    timestamp: '2026-07-22T14:29:30.894Z'
+                invalidViewboxLatitudeOrder:
+                  summary: '`min_lat` greater than `max_lat`'
+                  value:
+                    error: Invalid Viewbox Latitude
+                    message: Minimum latitude cannot be greater than maximum latitude in the viewbox.
+                    path: /v1.0/geocoder/search
+                    status: 400
+                    timestamp: '2026-07-22T14:30:11.104Z'
+                invalidViewboxLongitudeOrder:
+                  summary: '`min_lon` greater than `max_lon`'
+                  value:
+                    error: Invalid Viewbox Longitude
+                    message: Minimum longitude cannot be greater than maximum longitude in the viewbox.
+                    path: /v1.0/geocoder/search
+                    status: 400
+                    timestamp: '2026-07-22T14:30:11.104Z'
+        '404':
+          description: Not Found — No results matched the query
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                noResults:
+                  summary: Query matched no locations
+                  value:
+                    error: No Result Found
+                    message: No results found for the given query.
+                    path: /v1.0/geocoder/search
+                    status: 404
+                    timestamp: '2026-07-22T14:29:58.349Z'
+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:
+    ErrorResponse:
+      type: object
+      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).
+    ForwardGeocodeResponse:
+      type: array
+      title: Forward Geocoding Results
+      description: List of locations matching the search query, one entry per match, up to the number requested via `limit`.
+      items:
+        $ref: '#/components/schemas/GeocodeResponse'
+    GeocodeResponse:
+      type: object
+      description: A single geocoded location with coordinates and structured address components.
+      required:
+        - lat
+        - lon
+        - country_code
+        - country
+        - full_address
+        - bounding_box
+      properties:
+        lat:
+          type: number
+          format: float
+          description: WGS84 latitude value for the location.
+        lon:
+          type: number
+          format: float
+          description: WGS84 longitude value for the location.
+        name:
+          type: string
+          description: Name for the primary place searched.
+        category:
+          type: string
+          description: High-level category of the place, e.g. amenity, place, natural, building, highway.
+        type:
+          type: string
+          description: Specific kind within the category, e.g. fast_food, city, park, residential, house_number.
+        poi:
+          type: array
+          description: Points of interest at this location.
+          items:
+            $ref: '#/components/schemas/PointOfInterest'
+        street:
+          type: string
+          description: Street or road name.
+        area:
+          type: string
+          description: Intra-city area below city level, e.g. suburb, borough, ward, district, tehsil, neighbourhood.
+        postcode:
+          type: string
+          description: Postal code of the area.
+        city:
+          type: string
+          description: Settlement label appropriate to the country, e.g. city, town, municipality.
+        county:
+          type: string
+          description: Second-tier administrative area, e.g. county, district, prefecture.
+        state_code:
+          type: string
+          description: Subdivision code, typically ISO-3166-2 (e.g. US-TX, PK-PB).
+        state:
+          type: string
+          description: First-tier administrative area, e.g. state, region, province, division.
+        country_code:
+          type: string
+          description: Two-letter country code in upper case, ISO-3166-1 alpha-2.
+        country:
+          type: string
+          description: Country name of the searched place.
+        full_address:
+          type: string
+          description: Single-line, human-readable address of the location.
+        bounding_box:
+          type: array
+          description: Extent of the feature as `[lat_min, lat_max, lon_min, lon_max]` in WGS84 decimal degrees.
+          items:
+            type: string
+          minItems: 4
+          maxItems: 4
+    PointOfInterest:
+      type: object
+      description: A point of interest located at or near a geocoded result.
+      properties:
+        name:
+          type: string
+          description: Name of the point of interest.
+        category:
+          type: string
+          description: High-level category of the point of interest, e.g. amenity, place, natural, building, highway.
+        type:
+          type: string
+          description: Specific kind within the category, e.g. fast_food, city, park, residential, house_number.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []