Get Industry Classifications from a variety of vendors.
openapi: 3.0.0
info:
version: 1.0.1
title: Factset Classifications API
contact:
name: FactSet Research Systems
email: [email protected]
description: >
The Classifications API gives access to various Industry Classifications for
a given list of securities. Beginning first with GICS Direct, the service
will then expand to offering NAICS, SIC, RBICS, and more.
servers:
- url: https://api.factset.com/content
description: Production
security:
- BasicAuth: []
tags:
- name: Classifications
paths:
/classifications/v1/gics:
get:
tags:
- Classifications
summary: Factset Gets the GICS Direct Classifications
operationId: getGics
description: >
Gets the **Global Industry Classification Standard ("GICS")** Sectors,
Industry Group, Industry, and Sub-Industry Names and Numbers for a
requested list of ids and date range. All economic sectors have a
two-digit identification code, all industry groups have a four-digit
identification code, all industries have a six-digit identification
code, and all sub-industries have an eight-digit identification code. To
access the complete GICS structure and definitions, visit the [MSCI
GICS](https://www.msci.com/gics) or [S&P
GICS](https://www.spglobal.com/spdji/en/landing/topic/gics/) home pages.
Coverage includes over 37,000 securities.
*Licensing for GICS Classifications, Regions, and History is required in
addition to FactSet API license. Reach out to your FactSet Account Team
for assistance.*
parameters:
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- $ref: '#/components/parameters/frequency'
- $ref: '#/components/parameters/calendar'
responses:
'200':
description: GICS Response Object
content:
application/json:
schema:
$ref: '#/components/schemas/gicsResponse'
examples:
Multiple IDs as of latest month end:
$ref: '#/components/examples/gicsMultipleExample'
Security with GICS Change:
$ref: '#/components/examples/gicsChangeExample'
'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:
- Classifications
summary: Factset Returns the GICS classifications for the requested 'ids' and date range.
description: >
Gets the **Global Industry Classification Standard ("GICS")** Sectors,
Industry Group, Industry, and Sub-Industry Names and Numbers for a
requested list of ids and date range. All economic sectors have a
two-digit identification code, all industry groups have a four-digit
identification code, all industries have a six-digit identification
code, and all sub-industries have an eight-digit identification code. To
access the complete GICS structure and definitions, visit the [MSCI
GICS](https://www.msci.com/gics) or [S&P
GICS](https://www.spglobal.com/spdji/en/landing/topic/gics/) home pages.
Coverage includes over 37,000 securities.
*Licensing for GICS Classifications, Regions, and History is required in
addition to FactSet API license. Reach out to your FactSet Account Team
for assistance.*
operationId: postGics
requestBody:
required: true
description: Requests GICS Classifications for the given identifier and date range.
content:
application/json:
schema:
$ref: '#/components/schemas/gicsRequest'
responses:
'200':
description: GICS Direct Response Items
content:
application/json:
schema:
$ref: '#/components/schemas/gicsResponse'
examples:
Multiple IDs as of latest month end:
$ref: '#/components/examples/gicsMultipleExample'
Security with GICS Change:
$ref: '#/components/examples/gicsChangeExample'
'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
required: true
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 1000
description: >
The requested list of security identifiers. Accepted ID types include
Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids.
<p>***ids limit** = 1000 per request*</p> *<p>Make note, GET Method URL
request lines are also limited to a total length of 8192 bytes (8KB). In
cases where the service allows for thousands of ids, which may lead to
exceeding this request line limit of 8KB, its advised for any requests
with large request lines to be requested through the respective "POST"
method.</p>*
startDate:
name: startDate
in: query
required: false
schema:
type: string
description: Requested start date expressed in YYYY-MM-DD format.
endDate:
name: endDate
in: query
required: false
schema:
type: string
description: Requested End Date for Range expressed in YYYY-MM-DD format.
currency:
name: currency
in: query
required: false
schema:
type: string
description: Currency for response.
frequency:
name: frequency
in: query
schema:
type: string
enum:
- D
- W
- M
- AM
- CQ
- AY
- CY
default: M
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.
calendar:
name: calendar
in: query
schema:
type: string
enum:
- FIVEDAY
- SEVENDAY
default: FIVEDAY
description: Calendar of data returned. SEVENDAY includes weekends.
schemas:
gicsRequest:
type: object
title: GICS POST Request Model
properties:
ids:
$ref: '#/components/schemas/ids'
startDate:
$ref: '#/components/schemas/startDate'
endDate:
$ref: '#/components/schemas/endDate'
frequency:
$ref: '#/components/schemas/frequency'
calendar:
$ref: '#/components/schemas/calendar'
required:
- ids
gicsResponse:
title: GICS Response
type: object
properties:
data:
description: |
Array of GICS Objects, representing all requested ids and dates.
type: array
items:
$ref: '#/components/schemas/gics'
gics:
title: GICS Object
type: object
properties:
fsymId:
type: string
description: >-
FactSet Entity Identifier by default, otherwise returns FactSet
Regional Identifier. This is a six alpha-numeric characters,
excluding vowels, with an -E suffix (XXXXXX-E).
example: 0FPWZZ-E
date:
description: Date in YYYY-MM-DD for the classification record from GICS Direct
type: string
format: date
example: '2020-10-30'
gicsSectorName:
description: GICS Sector Name in Proper Format.
type: string
example: Communications Services
gicsSectorNumber:
description: GICS Sector Number
type: string
example: '50'
gicsIndustryGroupName:
description: GICS Industry Group Name in Proper Format.
type: string
example: Media & Entertainment
gicsIndustryGroupNumber:
description: GICS Industry Group Number
type: string
example: '5020'
gicsIndustryName:
description: GICS Industry Name in Proper Format.
type: string
example: Interactive Media & Services
gicsIndustryNumber:
description: GICS Industry Number
type: string
example: '502030'
gicsSubIndustryName:
description: GICS Sub-Industry Name in Proper Format.
type: string
example: Interactive Media & Services
gicsSubIndustryNumber:
description: GICS Industry Number.
type: string
example: '50203010'
requestId:
type: string
description: Identifier specified in the request
example: SPY-US
ids:
title: Security Ids
type: array
items:
type: string
minItems: 1
maxItems: 1000
description: >
The requested list of security identifiers. Accepted ID types include
Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids.
<p>***ids limit** = 1000 per request*</p> *<p>Make note, GET Method URL
request lines are also limited to a total length of 8192 bytes (8KB). In
cases where the service allows for thousands of ids, which may lead to
exceeding this request line limit of 8KB, its advised for any requests
with large request lines to be requested through the respective "POST"
method.</p>*
example:
- AAPL-US
startDate:
title: Start Date
type: string
description: Requested start date expressed in YYYY-MM-DD format.
example: '2018-12-31'
endDate:
title: End Date
type: string
description: Requested end date for Range expressed in YYYY-MM-DD format.
example: '2019-12-31'
frequency:
title: Frequency
type: string
enum:
- D
- W
- M
- AM
- CQ
- AY
- CY
default: M
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
calendar:
title: Calendar
type: string
enum:
- FIVEDAY
- SEVENDAY
default: FIVEDAY
description: Calendar of data returned. SEVENDAY includes weekends.
example: FIVEDAY
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: /classifications/v1/{endpoint}
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
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 Connectivity 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 server 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 - forbidden:
$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 - Unsupported Media Type:
$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:
gicsMultipleExample:
summary: Fetching GICS Direct Classifications for two securities
description: >-
Fetching GICS Direct Classifications for XOM and APPL as of latest
completed period.
value:
data:
- date: '2020-10-30'
fsymId: 0FPWZZ-E
gicsIndustryGroupName: Media & Entertainment
gicsIndustryGroupNumber: '5020'
gicsIndustryName: Interactive Media & Services
gicsIndustryNumber: '502030'
gicsSectorName: Communication Services
gicsSectorNumber: '50'
gicsSubIndustryName: Interactive Media & Services
gicsSubindustryNumber: '50203010'
requestId: GOOGL
- date: '2020-10-30'
fsymId: 002Q0G-E
gicsIndustryGroupName: Energy
gicsIndustryGroupNumber: '1010'
gicsIndustryName: Oil Gas & Consumable Fuels
gicsIndustryNumber: '101020'
gicsSectorName: Energy
gicsSectorNumber: '10'
gicsSubIndustryName: Integrated Oil & Gas
gicsSubindustryNumber: '10102010'
requestId: XOM
gicsChangeExample:
summary: Fetching GICS Classifications for Security with Changes
description: >-
Fetching Acadia Realty Trust (AKR-US) in 2016 over period in which
classifications changed from Financials to Real Estate.
value:
data:
- date: '2016-08-31'
fsymId: 00263C-E
gicsIndustryGroupName: Real Estate
gicsIndustryGroupNumber: '4040'
gicsIndustryName: Real Estate Investment Trusts (REITs)
gicsIndustryNumber: '404020'
gicsSectorName: Financials
gicsSectorNumber: '40'
gicsSubIndustryName: Retail REITs
gicsSubindustryNumber: '40402060'
requestId: AKR-US
- date: '2016-09-30'
fsymId: 00263C-E
gicsIndustryGroupName: Real Estate
gicsIndustryGroupNumber: '6010'
gicsIndustryName: Equity Real Estate Investment Trusts (REITs)
gicsIndustryNumber: '601010'
gicsSectorName: Real Estate
gicsSectorNumber: '60'
gicsSubIndustryName: Retail REITs
gicsSubindustryNumber: '60101070'
requestId: AKR-US
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: /classifications/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: /classifications/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: /classifications/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: /classifications/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: /classifications/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: /classifications/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: /classifications/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 server 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: /classifications/v1/{endpoint}
message: >-
USERNAME-SERIAL does not have permission to use
/classifications/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: /classifications/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: /classifications/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: /classifications/v1/{endpoint}
message: Unexpected error
subErrors: