openapi: 3.0.0
info:
version: 1.0.0
title: Factset Foreign Exchange Rates API
contact:
name: FactSet Research Systems
email: [email protected]
description: >
Foreign Exchange Rates API in which retrieves Spots and Forwards for a given
currency pair and date range. <p>*Spots and Forwards rates are sourced from
W/M Reuters.The WM Company calculates daily standardized spot rates for
global foreign exchange transactions, using rates provided by Reuters. These
rates are recognized globally as the standard by banks, fund managers, and
index compilers; increasingly these rates are also being used for benchmark
currency trading. In 1994, WM Company began calculating closing spot rates.
Closing spot rates provide a standard set of currency rates so that
portfolio valuations can be compared to each other and their performances
measured against benchmarks, without having discrepancies caused by exchange
rates. Closing spot rates are recorded at 16:00 GMT.*</p>
servers:
- url: https://api.factset.com/content
description: Production
security:
- BasicAuth: []
paths:
/foreign-exchange/v1/spots:
get:
tags:
- Foreign Exchange
summary: Factset Gets spots for a list of currency pairs
operationId: getSpots
description: >
Gets FX Spot rates for a requested currency pair, date range, and
frequency. The WM Company calculates daily standardized spot rates for
global foreign exchange transactions, using rates provided by Reuters.
These rates are recognized globally as the standard by banks, fund
managers, and index compilers; increasingly these rates are also being
used for benchmark currency trading.
parameters:
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- $ref: '#/components/parameters/frequency'
responses:
'200':
description: Array of ids Spot Rates for the date range and frequency requested
content:
application/json:
schema:
$ref: '#/components/schemas/spotsResponse'
examples:
Spot Rate of USDGBP:
$ref: '#/components/examples/usdGBPSpot'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
post:
tags:
- Foreign Exchange
summary: Factset Gets spots for a list of currency pairs
description: >
Gets FX Spot rates for a requested currency pair, date range, and
frequency. The WM Company calculates daily standardized spot rates for
global foreign exchange transactions, using rates provided by Reuters.
These rates are recognized globally as the standard by banks, fund
managers, and index compilers; increasingly these rates are also being
used for benchmark currency trading.
operationId: getSpotsForList
requestBody:
required: true
description: Request object for Spots.
content:
application/json:
schema:
$ref: '#/components/schemas/spotsRequest'
examples:
Single Currency Spot Rate for Year 2019 on Daily Basis:
$ref: '#/components/examples/singleCurrencySpot'
List of Key Currency Pair Spot Rates for Year 2019 on Monthy Basis:
$ref: '#/components/examples/keyCurrencySpot'
responses:
'200':
description: Array of spots
content:
application/json:
schema:
$ref: '#/components/schemas/spotsResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/foreign-exchange/v1/forwards:
get:
tags:
- Foreign Exchange
summary: Factset Gets Forwards for a list of currency pairs
operationId: getFXForwards
description: >
Forward rates are provided in 80+ currencies against the U.S. dollar,
British pound, and euro. Forward quotes are provided by Reuters and
coverage is determined by the amount of reliable currency trading in a
particular currency. Bid, offer, and mid rates are available for 11
`forwardPeriod` periods - Overnight, Tomorrow Next, 1 Week (Spot Week),
1 month, 2 month, 3 month, 6 month, 9 month, 1 year, 2 year, 5 year. All
identifiers have spot rates, but not all identifiers have forward rate
data.
parameters:
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/forwardPeriod'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- $ref: '#/components/parameters/frequency'
responses:
'200':
description: >-
Array of ids Forward Rates for the date range and frequency
requested
content:
application/json:
schema:
$ref: '#/components/schemas/forwardsResponse'
examples:
Forward Rate of USDGBP:
$ref: '#/components/examples/usdGBPForward'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
post:
tags:
- Foreign Exchange
summary: Factset Gets Forwards for a list of currency pairs
description: >
Forward rates are provided in 80+ currencies against the U.S. dollar,
British pound, and euro. Forward quotes are provided by Reuters and
coverage is determined by the amount of reliable currency trading in a
particular currency. Bid, offer, and mid rates are available for 11
`forwardPeriod` periods - Overnight, Tomorrow Next, 1 Week (Spot Week),
1 month, 2 month, 3 month, 6 month, 9 month, 1 year, 2 year, 5 year. All
identifiers have spot rates, but not all identifiers have forward rate
data.
operationId: getFXForwardsForList
requestBody:
required: true
description: Request object for FX Forwards.
content:
application/json:
schema:
$ref: '#/components/schemas/forwardsRequest'
examples:
Latest Birtish Pound Per US Dollar One Month Forward:
$ref: '#/components/examples/usdGBPForwardPost'
responses:
'200':
description: Array of forward rates
content:
application/json:
schema:
$ref: '#/components/schemas/forwardsResponse'
examples:
British Pound to US Dollar Forward Rate:
$ref: '#/components/examples/usdGBPForward'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
parameters:
ids:
name: ids
in: query
schema:
type: array
items:
type: string
required: true
explode: false
description: >-
The currency pair requested in the format of a ISO {source}{target}. For
a complete list of ISO currencies, please visit [OA
1470](https://my.apps.factset.com/oa/pages/1470)
examples:
oneids:
summary: United States Dollar to Great British Pound
value:
- USDGBP
listOfKeyPairs:
summary: List of Key Pairs
value:
- EURUSD
- GBPUSD
- AUDUSD
- USDJPY
- USDCNY
- USDCAD
- USDCHF
- EURGBP
- EURCHF
- EURJPY
startDate:
name: startDate
in: query
required: false
schema:
type: string
description: >
The start date requested for a given date range in **YYYY-MM-DD**
format. If left blank, the API will default to latest available.
example: '2019-01-01'
endDate:
name: endDate
in: query
required: false
schema:
type: string
description: >
The end date requested for a given date range in **YYYY-MM-DD** format.
If left blank, the API will default to latest available.
example: '2019-12-31'
frequency:
name: frequency
in: query
schema:
type: string
enum:
- D
- W
- M
- AM
- CQ
- AY
- CY
default: D
description: |
Controls the display frequency of the data returned.
* **D** = Daily
* **W** = Weekly, based on the last day of the week of the start date.
* **M** = Monthly, based on the last trading day of the month.
* **AM** = Monthly, based on the start date (e.g., if the start date is June 16, data is displayed for June 16, May 16, April 16 etc.).
* **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).
* **AY** = Actual Annual, based on the start date.
* **CY** = Calendar Annual, based on the last trading day of the calendar year.
examples:
Daily:
summary: D - Daily frequency display based on trading calendar
value: D
Weekly:
summary: W - Weekly - based on the last day of the week of the start date
value: W
Monthly:
summary: M - Monthly - based on the last trading day of the month.
value: M
Actual Month:
summary: >-
AM - Actual Month - based on the startDate (e.g., if the start date
is June 16, data is displayed for June 16, May 16, April 16 etc.).
value: AM
Calendar Quarterly:
summary: >-
CQ - Calendar Quarterly - based on the last day of the week of the
startDate
value: CQ
Actual Annual:
summary: AY - Actual Annual - based on the the startDate
value: AY
Calendar Annual:
summary: >-
CY - Calendar Annual - based on the last trading day of the calendar
year.
value: CY
forwardPeriod:
name: forwardPeriod
in: query
schema:
type: string
enum:
- 'ON'
- TN
- SW
- 1M
- 2M
- 3M
- 6M
- 9M
- 1Y
- 2Y
- 5Y
default: 1M
description: >
Bid, offer, and mid rates are available for the following 11 time
periods.
* ON - Overnight
* TN - Tomorrow Next
* SW - One Week (Spot Week)
* 1M - One Month
* 2M - Two Months
* 3M - Three Months
* 6M - Six Months
* 9M - Nine Months
* 1Y - One Year
* 2Y - Two Years
* 5Y - Five Years
examples:
Overnight:
summary: ON - Overnight
value: 'ON'
Tomorrow Next:
summary: TN - Tomorrow Next
value: TN
One Week (Spot Week):
summary: SW - Spot Week
value: SW
One Month:
summary: 1M - One Month
value: 1M
Two Months:
summary: 2M - Two Months Forward
value: 2M
Three Months:
summary: 3M - Three Months Forward
value: 3M
Six Months:
summary: 6M - Six Months Forward
value: CY
Nine Months:
summary: 9M - Nine Months Forward
value: 9M
One Year:
summary: 1Y - One Year Forward
value: 1Y
Two Year:
summary: 2Y - Two Years Forward
value: CY
Five Year:
summary: 5Y - Five Years Forward
value: 5Y
schemas:
spotsRequest:
title: Spots Request Body
description: Spots Request Body
type: object
properties:
ids:
$ref: '#/components/schemas/ids'
startDate:
$ref: '#/components/schemas/startDate'
endDate:
$ref: '#/components/schemas/endDate'
frequency:
$ref: '#/components/schemas/frequency'
required:
- ids
spotsResponse:
type: object
title: Spots Response
properties:
data:
description: Array of Spot Objects
type: array
items:
$ref: '#/components/schemas/spot'
spot:
title: Spot Object
type: object
properties:
requestId:
description: >-
The FX Spot Rate currency pair requested in the 'ids' parameter.
This represents the base and quote currency.
type: string
example: USDGBP
currencyName:
description: The full text currency pair name expressed in Proper Case.
type: string
example: British Pounds per U.S. Dollar
spotBid:
description: The currency pair's spot rate Bid.
type: number
example: 0.799232737
spotMid:
description: The currency pair's spot rate Mid.
type: number
example: 0.799360512
spotAsk:
description: The currency pair's spot rate Ask.
type: number
example: 0.799488327
date:
description: Ending date for the period expressed in YYYY-MM-DD format.
type: string
format: date
example: '2020-07-07'
forwardsRequest:
title: Forwards Request Body
description: Forwards Request Body
type: object
properties:
ids:
$ref: '#/components/schemas/ids'
forwardPeriod:
$ref: '#/components/schemas/forwardPeriod'
startDate:
$ref: '#/components/schemas/startDate'
endDate:
$ref: '#/components/schemas/endDate'
frequency:
$ref: '#/components/schemas/frequency'
required:
- ids
forwardsResponse:
type: object
title: Forwards Response
properties:
data:
description: Array of Forward Objects
type: array
items:
$ref: '#/components/schemas/forward'
forward:
title: Forward Object
type: object
properties:
requestId:
description: >-
The FX Forward Rate currency pair requested in the 'ids' parameter.
This represents the base and quote currency.
type: string
example: USDGBP
currencyName:
description: The full text currency pair name expressed in Proper Case.
type: string
example: British Pounds per U.S. Dollar
forwardBid:
description: The currency pair's Forward Rate Bid.
type: number
example: 0.794937836
forwardMid:
description: The currency pair's Forward Rate Mid.
type: number
example: 0.795070563
forwardAsk:
description: The currency pair's Forward Rate Ask.
type: number
example: 0.795203333
date:
description: Ending date for the period expressed in YYYY-MM-DD format.
type: string
format: date
example: '2020-07-07'
forwardPeriod:
description: The Forward Time Period requested for the Currency Pair.
type: string
example: 1M
errorResponse:
type: object
title: Error Response
properties:
status:
description: status
type: string
example: Bad Request
timestamp:
description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
type: string
example: '2019-11-01 11:09:41.918'
format: date-time
path:
description: The Endpoint path {package}/version/{endpoint}
type: string
example: /foreign-exchange/v1/spots
message:
description: The plain text error message
type: string
example: Validation Error
subErrors:
description: subErrors related to the error message. Null if not applicable.
type: object
properties:
object:
description: the operation ID
type: string
field:
description: Parameter Field Name
type: string
message:
description: Error message
type: string
rejectedValue:
description: Rejected Values in an Array
type: array
items:
type: string
ids:
type: array
items:
type: string
description: >-
The currency pair requested in the format of a ISO {source}{target}. For
a complete list of ISO currencies, please visit [OA
1470](https://my.apps.factset.com/oa/pages/1470)
example:
- USDGBP
- USDEUR
startDate:
type: string
description: >
The start date requested for a given date range in **YYYY-MM-DD**
format. If left blank, the API will default to latest available.
example: '2019-01-01'
endDate:
type: string
description: >
The end date requested for a given date range in **YYYY-MM-DD** format.
If left blank, the API will default to latest available.
example: '2019-12-31'
frequency:
type: string
enum:
- D
- W
- M
- AM
- CQ
- AY
- CY
default: D
description: |
Controls the display frequency of the data returned.
* **D** = Daily
* **W** = Weekly, based on the last day of the week of the start date.
* **M** = Monthly, based on the last trading day of the month.
* **AM** = Monthly, based on the start date (e.g., if the start date is June 16, data is displayed for June 16, May 16, April 16 etc.).
* **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).
* **AY** = Actual Annual, based on the start date.
* **CY** = Calendar Annual, based on the last trading day of the calendar year.
example: M
forwardPeriod:
type: string
enum:
- 'ON'
- TN
- SW
- 1M
- 2M
- 3M
- 6M
- 9M
- 1Y
- 2Y
- 5Y
description: >
Bid, offer, and mid rates are available for the following 11 time
periods.
* ON - Overnight
* TN - Tomorrow Next
* SW - One Week (Spot Week)
* 1M - One Month
* 2M - Two Months
* 3M - Three Months
* 6M - Six Months
* 9M - Nine Months
* 1Y - One Year
* 2Y - Two Years
* 5Y - Five Years
default: 1M
responses:
'400':
description: >-
Bad Request. This can occur for several reasons. Please review the
"message" for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
examples:
Bad Request - Date Format:
$ref: '#/components/examples/badRequestDateFormat'
Bad Request - Missing Required Parameter:
$ref: '#/components/examples/badRequestRequiredParameter'
Bad Request - Future Date:
$ref: '#/components/examples/badRequestFutureDate'
Bad Request - Invalid Parameter:
$ref: '#/components/examples/badRequestInvalidParameters'
Bad Request - Malformed JSON:
$ref: '#/components/examples/badRequestMalformedJSON'
Bad Request - Read Timeout:
$ref: '#/components/examples/badRequestReadTimeout'
'401':
description: >-
Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have
successfully generated an API KEY for the IP range you are connecting
from. For more help, select the **Report Issue** in the top right corner
of this Developer Portal specification card and choose Connectivty 401
or 403 Responses.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
examples:
Bad Request - Date Format:
$ref: '#/components/examples/unauthenticated'
'403':
description: >-
The USERNAME-SERIAL attempted to request the endpoint is not authorized
to access. The request was a legal request, but the servier is refusing
to respond. Please reach out to FactSet Account Team for assistance with
authorization.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
examples:
Bad Request - Date Format:
$ref: '#/components/examples/forbidden'
'415':
description: >-
Unsupported Media Type. This error may be returned when the caller sends
a resource in a format that is not accepted by the server. This can be
fixed by ensuring that Content-Type header is set to the correct value.
In this instance, "application/json" would be the appropriate value.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
examples:
Bad Request - Date Format:
$ref: '#/components/examples/unsupportedMediaType'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
examples:
Internal Server Error - Not Writable:
$ref: '#/components/examples/notWritable'
Internal Server Error - General Exception:
$ref: '#/components/examples/generalException'
examples:
usdGBPSpot:
summary: Spot Rate of British Pounds per U.S. Dollar
description: Spot Rate of USDGBP
value:
data:
- requestId: USDGBP
currencyName: British Pounds per U.S. Dollar
spotAsk: 0.799488327
spotBid: 0.799232737
spotMid: 0.799360512
date: '2020-07-07'
singleCurrencySpot:
summary: Single Currency Pair Spot Rate for Calendar Year 2019
description: Single Currency Pair Spot Rate for Calendar Year 2019
value:
ids:
- USDGBP
startDate: '2019-01-01'
endDate: '2019-12-31'
frequency: D
keyCurrencySpot:
summary: >-
Spot Rates for a list of Key Currency Pairs for the Year of 2019 on a
Monthly Basis
description: >-
Spot Rates for a list of Key Currency Pairs for the Year of 2019 on a
Monthly Basis
value:
ids:
- EURUSD
- GBPUSD
- AUDUSD
- USDJPY
- USDCNY
- USDCAD
- USDCHF
- EURGBP
- EURCHF
- EURJPY
startDate: '2019-01-01'
endDate: '2019-12-31'
frequency: M
usdGBPForward:
summary: Forward Rate of British Pounds per U.S. Dollar
description: Forward Rate of USDGBP
value:
data:
- requestId: USDGBP
currencyName: British Pounds per U.S. Dollar
forwardBid: 0.794937836
forwardMid: 0.795070563
forwardAsk: 0.795203333
forwardPeriod: 1M
date: '2020-07-07'
usdGBPForwardPost:
summary: Single Currency Pair One Month Forward Rates for Calendar Year 2019
description: Single Currency Pair One Month Forward Rates for Calendar Year 2019
value:
ids:
- USDGBP
forwardPeriod: 1M
startDate: '2019-01-01'
endDate: '2019-12-31'
frequency: D
badRequestDateFormat:
summary: Bad Request - Date Format
description: >-
This bad request occurs when a request doesn't use the YYYY-MM-DD in the
date parameters. To resolve, convert your date to YYYY-MM-DD.
value:
status: Bad Request
timestamp: '2019-10-31 16:08:07.945'
path: /foreign-exchange/v1/{endpoint}
message: >-
The date parameter 'startDate' must be in the following date format:
YYYY-MM-DD
subErrors:
badRequestRequiredParameter:
summary: Bad Request - Required Parameter Missing
description: >-
This error message occurs when the request does not include the required
parameters. Required parameters are indicated with a red asterisks
symbol in the specification file.
value:
status: Bad Request
timestamp: '2020-06-12 15:48:42.016'
path: /foreign-exchange/v1/{endpoint}
message: The parameter 'ids' is required and may not be empty.
subErrors:
badRequestFutureDate:
summary: Bad Request - Future Date
description: >-
This error message occurs when a future date is requested in the
startDate and endDate parameters. Please revise your request to include
dates as of today's current date or any prior historical date.
value:
status: Bad Request
timestamp: '2020-06-12 15:52:48.091'
path: /foreign-exchange/v1/{endpoint}
message: >-
The use of future dates is not applicable in this endpoint. Please
revise your request to include dates up to today's current date.
subErrors:
badRequestInvalidParameters:
summary: Bad Request - Invalid Parameters
description: >-
This error message occurs when a request parameter is used in which is
not recognized by the service. Please revise your request to include
only the parameters listed in the specification. Typical causes are
spelling mistakes and use of improper casing.
value:
status: Bad Request
timestamp: '2020-06-12 15:58:54.068'
path: /foreign-exchange/v1/{endpoint}
message: >-
Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please
modify your request to use parameters outlined in the specification
for this endpoint.
subErrors:
badRequestMalformedJSON:
summary: Bad Request - Malformed JSON Request
description: >-
This error may be returned when the request body is specified as JSON,
but is not in proper JSON format.
value:
status: Bad Request
timestamp: '2019-11-05 09:48:29.18'
path: /foreign-exchange/v1/{endpoint}
message: Malformed JSON Request
subErrors:
badRequestReadTimeout:
summary: Bad Request - Read Timeout
description: >-
This error may be returned if it takes more than 29 seconds to hear back
from the data fetch service.
value:
status: Bad Request
timestamp: '2019-11-04 16:18:38.949'
path: /foreign-exchange/v1/{endpoint}
message: The request took too long. Try again with a smaller request.
subErrors:
unauthenticated:
summary: User Authentication Failed
description: >-
This occurs when a user is not properly authenticated or recognized by
the service. Please double check the USERNAME-SERIAL and API-Key used to
request and ensure you are within the IP range specified for the Key.
Report Issue under 401 error for help with troubleshooting.
value:
status: User Authentication Failed
timestamp: '2019-10-31 16:08:07.945'
path: /foreign-exchange/v1/{endpoint}
message: User Authentication Failed.
subErrors:
forbidden:
summary: Forbidden
description: >-
The USERNAME-SERIAL attempted to request the endpoint is not authorized
to access. The request was a legal request, but the servier is refusing
to respond. Please reach out to FactSet Account Team for assistance with
authorization.
value:
status: Forbidden
timestamp: '2020-06-12 16:08:51.731'
path: /foreign-exchange/v1/{endpoint}
message: >-
USERNAME-SERIAL does not have permission to use
/foreign-exchange/v1/{endpoint}
subErrors:
unsupportedMediaType:
summary: Unsupported Media Type
description: >-
This bad request occurs when the media type passed in the request is not
supported. Currently the APIs only support 'application/json'.
value:
status: Unsupported Media Type
timestamp: '2019-11-05 09:42:27.237'
path: /foreign-exchange/v1/{endpoint}
message: >-
text/html media type is not supported. Supported media types are
application/json
subErrors:
notWritable:
summary: Internal Server Error - Not Writable
description: >-
This error may be returned when the server encounters an error writing
the JSON response.
value:
status: Internal Server Error
timestamp: '2019-11-05 09:48:29.18'
path: /foreign-exchange/v1/{endpoint}
message: Error writing JSON output
subErrors:
generalException:
summary: Internal Server Error - General Exception
description: >-
This is the most general error that can be returned to by the service.
Please `Report Issue` to FactSet.
value:
status: Internal Server Error
timestamp: '2019-11-01 10:36:01.944'
path: /foreign-exchange/v1/{endpoint}
message: Unexpected error
subErrors:
tags:
- name: Foreign Exchange