openapi: 3.2.0
info:
  version: 1.0.2
  title: XE Currency Data Historic Rates API
  description: "XE Currency Data - Integrate your application with our globally trusted currency data.\n\n Get your free API credentials for 7 days <a href=\"https://xecd.xe.com/account/signup.php?freetrial\">here</a>"
servers:
- url: https://xecdapi.xe.com/v1
security:
- basicAuth: []
tags:
- name: Historic Rates
paths:
  /historic_rate:
    get:
      tags:
      - Historic Rates
      summary: Get historic rates for one base currency against one or more counter currencies.
      description: "The Currency Data API provides you with access to daily historical rates back to 1998. When retrieving historical rates through our Currency Data API, you would specify your requested currencies along with the date and/or date range and time (hh:mm). If your account is registered for a Live package then you have access to minutely rates for the past 7 days and outside of 7 days you have access to rates on the hour. Historical rates are available with all API packages. The time parameter (hh:mm) only applies to Live packages.\n The endpoint returns the historic rate for a single base currency and one or more counter currencies.\n\n<a href=\"https://xecdapi.xe.com/v1/historic_rate.csv/?from=USD&date=2011-03-05&to=CAD,EUR\">https://xecdapi.xe.com/v1/historic_rate.csv/?from=USD&date=2011-03-05&to=CAD,EUR</a>\n"
      parameters:
      - name: from
        in: query
        description: 'OPTIONAL – Currency you want to convert from ISO code.

          Note if this parameter is omitted, USD is assumed.

          '
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: "Comma separated list of to currencies ISO 4217 codes.\nThis will limit the data returned to only those currencies you are interested in. Use an asterisk * to specify all currencies.\n Note: Obsolete currencies are replaced by their precursor or successor currency. \n"
        required: true
        schema:
          type: string
      - name: amount
        in: query
        description: 'OPTIONAL – This parameter can be used to specify the amount you want to convert, if an amount is not specified then 1.00 is assumed.

          '
        required: false
        schema:
          type: number
      - name: date
        in: query
        description: 'UTC date should be in the form of YYYY-MM-DD, up to 1995-11-16.

          If your account is registered for a Daily package your endpoint will return rates at your preferred daily lock-in time.

          If your account is registered for a Live package your endpoint will return XE mid-day rate unless you specify a time parameter in your call request.

          '
        required: true
        schema:
          type: string
      - name: time
        in: query
        description: 'OPTIONAL – *Time parameter is applicable to Live package only*.

          UTC time is in format of HH:MM Time option is only available for the last 24 hours, if time is not specified, only one table is returned using the XE mid-day rates (As returned in http://www.xe.com/currencytables/)

          '
        required: false
        schema:
          type: string
      - name: obsolete
        in: query
        description: OPTIONAL – If ‘true’ then endpoint will display rates for currencies that are obsolete. If ‘false’ then obsolete currencies are replaced by their successor currency.
        required: false
        schema:
          type: boolean
      - name: inverse
        in: query
        description: OPTIONAL – If ‘true’ then endpoint will display the inverse of the converted value. If ‘false‘ then it will not be displayed.
        required: false
        schema:
          type: boolean
      - name: decimal_places
        in: query
        description: OPTIONAL – This parameter can be used to specify the number of decimal places included in the output. Example 1 USD to EUR = 0.874852 with decimal_places=3, the output returned will be EUR = 0.875
        required: false
        schema:
          type: number
      - name: margin
        in: query
        description: 'OPTIONAL – This parameter can be used to add a margin (-/+)  to XE''s mid-market rate. Example: add margin=2.05 parameter to the endpoint and the API will return our mid-market rates plus the margin of 2.05 percent'
        required: false
        schema:
          type: number
      responses:
        '200':
          description: OK
          headers:
            X-RateRequest-Limit:
              schema:
                type: number
            X-RateRequest-Remaining:
              schema:
                type: number
            X-RateRequest-Reset:
              schema:
                type: number
            X-RateLimit-Limit:
              schema:
                type: number
            X-RateLimit-Remaining:
              schema:
                type: number
            X-RateLimit-Reset:
              schema:
                type: number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricRateResponse'
        '400':
          description: Bad Request
          headers:
            X-RateRequest-Limit:
              schema:
                type: number
            X-RateRequest-Remaining:
              schema:
                type: number
            X-RateRequest-Reset:
              schema:
                type: number
            X-RateLimit-Limit:
              schema:
                type: number
            X-RateLimit-Remaining:
              schema:
                type: number
            X-RateLimit-Reset:
              schema:
                type: number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /historic_rate/period:
    get:
      tags:
      - Historic Rates
      summary: Get historic rates for one base currency against one or more counter currencies over a period of time.
      description: "This endpoint returns a daily historic rate for a single base currency and one or more counter currencies over a period of time.\n\n<a href=\"https://xecdapi.xe.com/v1/historic_rate/period.csv/?from=USD&to=CAD&start_timestamp=2017-09-01&end_timestamp=2017-11-30&per_page=500\">https://xecdapi.xe.com/v1/historic_rate/period.csv/?from=USD&to=CAD&start_timestamp=2017-09-01&end_timestamp=2017-11-30&per_page=500</a>\n\nOptional parameters available with Live accounts:\n\n&interval=minutely\n&interval=hourly \n"
      parameters:
      - name: from
        in: query
        description: 'OPTIONAL – Currency you want to convert from ISO code.  Note if this parameter is omitted, USD is assumed.

          '
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: "Comma separated list of to currencies based on ISO 4217 codes.\nThis will limit the data returned to only those currencies you are interested in.\n Note: Obsolete currencies are replaced by their precursor or successor currency. \n"
        required: true
        schema:
          type: string
      - name: amount
        in: query
        description: 'OPTIONAL – This parameter can be used to specify the amount you want to convert, if an amount is not specified then 1.00 is assumed.

          '
        required: false
        schema:
          type: number
      - name: start_timestamp
        in: query
        description: 'OPTIONAL - ISO 8601 timestamp in the format yyyy-mm-ddThh:mm giving the UTC date and time of the start of the period for which you would like rates returned.


          If your account is registered for a Daily package your endpoint will return rates at your preferred daily lock-in time starting on the date specified in your request.  If your account does not have a preferred daily lock-in time then rates will return as of 00:00 UTC

          If your account is registered for a Live package your endpoint will return rates starting at 00:00 UTC if no time portion is specified.

          '
        required: false
        schema:
          type: string
      - name: end_timestamp
        in: query
        description: 'OPTIONAL – ISO 8601 timestamp in the format yyyy-mm-ddThh:mm giving the UTC date and time of the end of the period for which you would like rates returned. If a time in the future is specified, the current time will be used. If no end_time is specified, the time specified in the  “start_timestamp” paramenter will also be used for the end_timestamp.”

          If your account is registered for a Daily package your endpoint will return rates at your preferred daily lock-in time ending on the date specified in your request.  If your account does not have a preferred daily lock-in time then rates will return as of 00:00 UTC.

          If your account is registered for a Live package your endpoint will return rates at 00:00 UTC unless you specify a time parameter in your rate request.

          '
        required: false
        schema:
          type: string
      - name: interval
        in: query
        description: "OPTIONAL – Interval is applicable to Live packages only.  Using one of the interval values below in your call request will return rates for that specific interval within the time period specified.\n\nExample: adding the interval of \"hourly\" will return rates for every hour in the time period you specified.\n\n  \"daily\" - Returns one rate for the days specified in your time period, \n\"hourly\" - Returns rates for every hour in the time period you specify\n\nIf omitted, \"daily\" is used.  This parameter is only used if both the \"start_timestamp\" and \"end_timestamp\" parameters have been specified"
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: 'OPTIONAL – You can specify the page number you want to request.

          Note: that page numbering is 1-based (the first page being page 1).

          Omitting this parameter will return the first page.

          '
        required: false
        schema:
          type: number
      - name: per_page
        in: query
        description: 'OPTIONAL – You can specify the number of results per page. The default is 30 results per page with a maximum of 500 results per page.

          '
        required: false
        schema:
          type: number
      - name: obsolete
        in: query
        description: OPTIONAL – If ‘true’ then endpoint will display rates for currencies that are obsolete. If ‘false’ then obsolete currencies are replaced by their successor currency.
        required: false
        schema:
          type: boolean
      - name: inverse
        in: query
        description: OPTIONAL – If ‘true’ then endpoint will display the inverse of the converted value. If ‘false‘ then it will not be displayed.
        required: false
        schema:
          type: boolean
      - name: decimal_places
        in: query
        description: OPTIONAL – This parameter can be used to specify the number of decimal places included in the output. Example 1 USD to EUR = 0.874852 with decimal_places=3, the output returned will be EUR = 0.875
        required: false
        schema:
          type: number
      - name: margin
        in: query
        description: 'OPTIONAL – This parameter can be used to add a margin (-/+)  to XE''s mid-market rate. Example: add margin=2.05 parameter to the endpoint and the API will return our mid-market rates plus the margin of 2.05 percent'
        required: false
        schema:
          type: number
      responses:
        '200':
          description: OK
          headers:
            X-RateRequest-Limit:
              schema:
                type: number
            X-RateRequest-Remaining:
              schema:
                type: number
            X-RateRequest-Reset:
              schema:
                type: number
            X-RateLimit-Limit:
              schema:
                type: number
            X-RateLimit-Remaining:
              schema:
                type: number
            X-RateLimit-Reset:
              schema:
                type: number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricRatePeriodResponse'
        '400':
          description: Bad Request
          headers:
            X-RateRequest-Limit:
              schema:
                type: number
            X-RateRequest-Remaining:
              schema:
                type: number
            X-RateRequest-Reset:
              schema:
                type: number
            X-RateLimit-Limit:
              schema:
                type: number
            X-RateLimit-Remaining:
              schema:
                type: number
            X-RateLimit-Reset:
              schema:
                type: number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RatePeriod:
      properties:
        mid:
          type: number
        timestamp:
          type: string
    HistoricRatePeriodResponse:
      properties:
        terms:
          type: string
        privacy:
          type: string
        from:
          type: string
        amount:
          type: number
        to:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/RatePeriod'
    ErrorResponse:
      properties:
        code:
          type: number
        message:
          type: string
        documentationUrl:
          type: string
    HistoricRateResponse:
      properties:
        terms:
          type: string
        privacy:
          type: string
        from:
          type: string
        amount:
          type: number
        timestamp:
          type: string
        to:
          type: array
          items:
            $ref: '#/components/schemas/Rate'
    Rate:
      properties:
        quotecurrency:
          type: string
        mid:
          type: number
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic