openapi: 3.0.3
info:
  title: Zipwise Web Services - accountinfo
  description: >
    Returns information about the calling account: the IP address on file,
    daily call usage, and the maximum radius allowed for the `radius` method.
    Unlike the other four Zipwise methods, `accountinfo` does not call the shared
    account_check.php validator - it looks up the account directly and does not
    increment the account's daily call counter.
  version: "2026-04"
servers:
  - url: https://www.zipwise.com/webservices

paths:
  /accountinfo.php:
    get:
      operationId: accountInfo
      summary: Get account usage and limits
      description: >
        The service also accepts these same parameters via POST instead of GET.
        Calls are rate-limited per session to one every 0.5 seconds.
      parameters:
        - name: key
          in: query
          required: true
          description: Your 16-character API key.
          schema:
            type: string
            pattern: '^[a-z0-9]{16}$'
        - name: format
          in: query
          required: false
          description: Response format. Anything other than `json` (including omitted) returns XML.
          schema:
            type: string
            enum: [xml, json]
            default: xml
      responses:
        "200":
          description: >
            Always returns HTTP 200. Successful requests and errors are both
            distinguished by the response body (presence of an `<error>` /
            `"error"` field), not by HTTP status.
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/AccountInfoResultXml'
              examples:
                success:
                  summary: Successful result
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <results>
                      <ip_address>12.34.56.78</ip_address>
                      <calls_used>225</calls_used>
                      <calls_remaining>275</calls_remaining>
                      <max_radius>500</max_radius>
                    </results>
                error:
                  summary: Error result
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <results>
                      <error>Description of the error</error>
                    </results>
            application/json:
              schema:
                $ref: '#/components/schemas/AccountInfoResultJson'
              examples:
                success:
                  summary: Successful result
                  value:
                    results:
                      ip_address: "12.34.56.78"
                      calls_used: "225"
                      calls_remaining: "275"
                      max_radius: "500"
                error:
                  summary: Error result
                  value:
                    results:
                      error: Description of the error

components:
  schemas:
    AccountInfoResultXml:
      type: string
      description: XML document with a `<results>` root containing either the fields below or a single `<error>` element.

    AccountInfoResultJson:
      type: object
      properties:
        results:
          oneOf:
            - type: object
              properties:
                ip_address:
                  type: string
                  description: IP address on file for the account (from the last call, or the account's registered IP).
                calls_used:
                  type: string
                  description: Number of calls used against the account today.
                calls_remaining:
                  type: string
                  description: calls_used subtracted from the account's daily limit for its service tier.
                max_radius:
                  type: string
                  description: Maximum radius (miles) permitted for the radius method at this account's service tier.
            - type: object
              properties:
                error:
                  type: string

x-notes:
  - "Daily call limit and max_radius by service tier: free=50/50mi, tier19=500/500mi, tier39=2500/2500mi, tier59=5000/5000mi, tier99=10000/10000mi, tier299=10000000/1000000mi."
  - "If the account's last billing attempt failed (last_result_ws='FAIL'), limit and max_radius are both forced down to the free tier (50), and an error directs the caller to log in and update billing."
  - "Possible error messages: '{key} is not a recognizable API key.' (wrong length), 'You did not provide an API key.' (empty), 'Please wait 0.5 between calls.' (rate limit), 'That API key is not recognized.' (not found in database), 'Your account is not current. Please log in at https://www.zipwise.com/webservices/account.php' (failed billing)."
