openapi: 3.2.0 info: title: Dtn Information API version: '1.0' description: 'Operations tagged Information across 2 of this provider''s published API definitions: dtn-financial-market-data-openapi.json, dtn-storm-risk-analytics-api-openapi.json. Each path carries the servers of the definition it was published in.' servers: - description: Production (PROD) url: https://pxweb.dtn.com - description: Customer Acceptance Testing (CAT) url: https://pxwebcat.dtn.com - description: QA Testing (PRE) url: https://prx-ws-pre.dtn.com - description: Development (DEV) url: https://prx-app1-dev.dtn.com - url: https://sra.dtn.com/v1 tags: - name: Information paths: /market_data/symbol-search: get: tags: - Information summary: Keyword symbol search description: "Search for symbols with a keyword search of the symbol's description, meta-data, and symbol.\n\n\n**Note: The Dev Portal 'Try' feature does not currently work for the Market Data API. To try the API, please see this site: https://pxweb.dtn.com/PXWebDoc/OAS/index.html or use the attached Postman collection. Contact DTN here: https://www.dtn.com/contact-us/ for a trial account.** \n" operationId: symbolSearch parameters: - $ref: '#/components/parameters/searchTextParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: The request was successful. content: application/json: schema: type: object properties: meta: $ref: '#/components/schemas/Meta' data: type: array items: $ref: '#/components/schemas/SymbolSearchSymbol' 5XX: description: An internal server error has occurred. Sending the error response to support will help with troubleshooting. content: application/json: schema: $ref: '#/components/schemas/Error' servers: - description: Production (PROD) url: https://pxweb.dtn.com - description: Customer Acceptance Testing (CAT) url: https://pxwebcat.dtn.com - description: QA Testing (PRE) url: https://prx-ws-pre.dtn.com - description: Development (DEV) url: https://prx-app1-dev.dtn.com /market_data/metadata/market-hours: get: tags: - Information summary: Get market hours description: "Retrieve the hours a security is open for trading including schedule changes for holidays.\n\n\n**Note: The Dev Portal 'Try' feature does not currently work for the Market Data API. To try the API, please see this site: https://pxweb.dtn.com/PXWebDoc/OAS/index.html or use the attached Postman collection. Contact DTN here: https://www.dtn.com/contact-us/ for a trial account.** \n" operationId: getMarketHours parameters: - $ref: '#/components/parameters/symbolParam' - $ref: '#/components/parameters/startDateParam' - $ref: '#/components/parameters/endDateParam' - $ref: '#/components/parameters/symbolLimitParam' - $ref: '#/components/parameters/pageTokenParam' - $ref: '#/components/parameters/marketParam' responses: '200': description: Success content: application/json: schema: type: object properties: meta: $ref: '#/components/schemas/Meta' data: type: array items: $ref: '#/components/schemas/HoursSymbol' 5XX: description: An internal server error has occurred. Sending the error response to support will help with troubleshooting. content: application/json: schema: $ref: '#/components/schemas/Error' servers: - description: Production (PROD) url: https://pxweb.dtn.com - description: Customer Acceptance Testing (CAT) url: https://pxwebcat.dtn.com - description: QA Testing (PRE) url: https://prx-ws-pre.dtn.com - description: Development (DEV) url: https://prx-app1-dev.dtn.com /regions: get: tags: - Information summary: Get predefined named regions. description: Returns all available predefined regions currently stored in the SRA prediction system. These values can be used to quickly get predictions for regions without needing to know the exact list of FIPS. operationId: getNamedRegions responses: '200': description: Success content: application/json: schema: type: array items: type: string example: - CONUS - MIDWEST - US_SW security: - clientCredentials: [] servers: - url: https://sra.dtn.com/v1 /fips/region/{region}: get: tags: - Information summary: Get FIPS for counties within redefined region. description: 'Passing in a predefined region name will return a list of counties contained within the region. The "county" objects will contain general information about the county including known substation count, population, and total area (in square miles). ' operationId: getRegionFips parameters: - $ref: '#/components/parameters/region' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/fips' security: - clientCredentials: [] servers: - url: https://sra.dtn.com/v1 /fips/state/{state}: get: tags: - Information summary: Get FIPS for counties within state. description: 'Passing in a state name or abbreviation will return a list of counties contained within the state. The "county" objects will contain general information about the county including known substation count, population, and total area (in square miles). ' operationId: getStateFips parameters: - $ref: '#/components/parameters/state' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/fips' security: - clientCredentials: [] servers: - url: https://sra.dtn.com/v1 components: schemas: Meta: type: object properties: timestamp: type: string format: date-time count: type: number description: Number of symbols returned by request dataSrc: type: string description: A value used by DTN support for troublshooting any issues duration: type: string description: The duration of time DTN servers spent processing the request. Does not include internet transit time. userId: type: string description: The user that made the request. operation: type: string description: The name of the operation called pageToken: type: string description: A page token returned from a previous request. It is used to resume a request that matched more symbols than the Limit allowed in one request. HoursSymbol: type: object properties: symbol: $ref: '#/components/schemas/Symbol' days: type: array items: $ref: '#/components/schemas/HoursDate' required: - symbol - days HoursSession: type: object properties: open: type: string format: date-time close: type: string format: date-time required: - open - close HoursDate: type: object properties: date: type: string format: date sessions: type: array items: $ref: '#/components/schemas/HoursSession' required: - date - sessions Symbol: required: - status - marketName - tickerSymbol - vendor type: object properties: status: type: number description: Indicate if this symbol/pattern was successfully queried. OK=0, 1=Not Found, 2=Not perm marketName: type: string description: Market symbol belongs too. examples: - CBOT requestedSymbol: type: string description: The symbol or pattern requested. examples: - '@C`##' tickerSymbol: type: string description: "The official current ticker symbol. This might be different than the requested symbol if the requested symbol was a search pattern or alias. \n" examples: - '@CU18' vendor: type: string description: Vendor for symbol. examples: - DTN description: Symbol identifier and request status. SymbolSearchSymbol: required: - tickerSymbol - marketName - description type: object properties: tickerSymbol: type: string description: The matched symbol. marketName: type: string description: Market symbol belongs too. examples: - CBT - CME description: type: string description: Text describing the symbol. Error: type: object properties: meta: type: object properties: type: type: string description: A more detailed or finer grained type declaration. In some cases could be a 'class' to assist with automated Exception throwing. eventId: type: string description: A UUID that represents this unique request. This can be used to help troubleshoot errors. dateTime: type: string format: date-time description: Repeat of optional dateTime from the messages section. messages: type: array items: type: object properties: type: type: string description: The error type. These can vary and have a general definition of the potential problem. Some potential values are ERROR, NotFound, InvalidParameters, NotAuthorized. examples: - NotAuthorized id: type: string description: An identifier for the error. This can represent a unique identifier for the error that occurred, but in many cases a unique number does not exist and it might simply be a 500. Some API's will make better use of this value and it will be used to help track down particular problems. examples: - '401' status: type: integer format: int32 description: Deprecated - this represents the HTTP Status code, but should not be used or relied upon. Future version will remove this. examples: - 401 message: type: string description: A concise description for the error. In some cases the description may provide means to resolve the problem. examples: - Unauthorized access to service. fips: type: object properties: fedId: type: string example: '27053' description: FIPS of county. fedName: type: string example: Hennepin description: Name of county. fedParentId: type: string example: '27' description: FIPS code for parent state. fedParentName: type: string example: Minnesota description: Name of parent state. fedParentAbbreviation: type: string example: MN description: Abbreviated name of parent state. substationCount: type: number example: 50 description: Total number of known substations in county. population: type: number example: 1267416 description: Population of county. Can be 0 if data unknown. totalArea: type: number example: 607 description: Area of county in square miles. parameters: endDateParam: name: endDate in: query description: The latest date to include in the result. Date in ISO 8601 format YYYY-MM-DD schema: type: string format: date searchTextParam: name: searchText in: query description: Keywords to match against symbols and their descriptions required: true schema: type: string startDateParam: name: startDate in: query description: Earliest date to include in the result. Date in ISO 8601 format YYYY-MM-DD schema: type: string format: date limitParam: name: limit in: query description: The maximum number of symbols to return. schema: type: integer default: 200 maximum: 4998 symbolLimitParam: name: symbolLimit in: query description: The number of symbols to return in one request up to a maximum of 4000. schema: type: integer default: 600 maximum: 4000 pageTokenParam: name: pageToken in: query description: "A page token returned from a previous request. It is used to resume a request that \n matched more symbols than the SymbolLimit allowed in one request. More information on how to \n make requests for many symbols can be found here: [https://pxweb.dtn.com/PXWebDoc/pages/ManySymbols.aspx](https://pxweb.dtn.com/PXWebDoc/pages/ManySymbols.aspx)\n" schema: type: string marketParam: name: market in: query description: 'A market identifier to apply to all symbols and patterns in the request. A list of markets can be found here: [https://pxweb.dtn.com/PXWebDoc/pages/Markets.aspx](https://pxweb.dtn.com/PXWebDoc/pages/Markets.aspx) ' schema: type: string symbolParam: name: symbol in: query description: 'A comma separated list of security symbols, security aliases, or search patterns. Information about search patterns can be found here: [https://pxweb.dtn.com/PXWebDoc/pages/SearchPatterns.aspx](https://pxweb.dtn.com/PXWebDoc/pages/SearchPatterns.aspx) Keyword based symbol search can be done with the /market_data/symbol-search endpoint. Or symbols can be searched for manually here: [https://ws1.dtn.com/PX/Search/](https://ws1.dtn.com/PX/Search/) ' required: true examples: corn: summary: CBOT Corn Front Month Alias value: '@C@1' oil: summary: NYMEX Crude Oil Front Month Alias value: QCL@1 msft: summary: Microsoft stock value: MSFT countyAverage: summary: CORN/YELLOW, County Average Spot Cash Price, Pipestone, MN value: CORN$.MN.F27117 schema: type: string state: name: state description: Name or abbreviation of state example: MN in: path required: true schema: type: string region: name: region description: Name of predefined region example: CONUS in: path required: true schema: type: string securitySchemes: clientCredentials: type: oauth2 x-receive-token-in: request-body flows: clientCredentials: tokenUrl: https://api.auth.dtn.com/v1/tokens/authorize description: "# Using DAIS for M2M/API Auth\nYou have been given a Client ID and a Client Secret, which are used to request a DTN Access Token. DTN Access Tokens are required when making calls to each and every DTN API endpoint. The following information provides additional details on these tokens and how they are generated.\n## What is an Access Token and how is it different from an API Key?\nAn API Key is a random string of characters that an API uses to authorize whether or not a calling client has approved access to an endpoint. These keys are a non-standard approach to API authorization and are generally issued on a per-API basis.\n\nAn Access Token is also a string of characters but is a base-64 encoded JavaScript Object Notation Web Token, or JWT. JWTs are a widely accepted standard that use OAuth concepts and approaches. \n\nBoth API Keys and Access Tokens are used in an Authorization Request Header as a Bearer, meaning there is no difference in where you put this string of characters when you make calls to DTN APIs.\n## How to generate an Access Token?\nWhen requested, an Access Token is generated for your specific Client (ID/Secret) and for a specific API. The DTN Auth and Identity Service (DAIS) generates new Access Tokens for your client. The DAIS endpoint is `POST https://api.auth.dtn.com/v1/tokens/authorize`.\n\nThis endpoint takes two Header parameters:\n * `Content-Type: application/json`\n * `Accept: application/json`\n\nThis endpoint takes four parameters in the Request Body:\n * `grant_type`: this should always be client_credentials for generating machine-to-machine tokens.\n * `client_id`: this is the Client ID or Application ID using the token and is given to you by DTN's Identity Team. This ID will never change for your client/application.\n * `client_secret`: this is the Client Secret that is associated with the Application ID and is given to you by DTN's Identity Team. This key is subject to rotation for security purposes but always with the client's knowledge.\n * `audience`: this is the API for which this Access Token will be used. For the DTN Market Data, you need to use the following audience: https://pxweb.dtn.com\n\nYou can use this CURL command template as a reference for obtaining an access token:\n ```\n curl --location --request POST 'https://api.auth.dtn.com/v1/tokens/authorize' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\"grant_type\": \"client_credentials\",\n\"client_id\": \"insert your client id here\",\n\"client_secret\": \"insert your client secret here\",\n\"audience\": \"insert your audience here\"\n}' \n ```\n\n*This document, for demonstration purposes, supplies a client_id and client_secret in all code examples. This client/application is for a fictitious API and cannot be used in practice to gain unauthorized access to any other DTN API.*\nUpon generating a new Access Token, you should receive an HTTP Response from DAIS similar to this:\n ```\n {\n \"data\": {\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw\",\n \"scope\": \"read:demo create:demo update:demo\",\n \"expires_in\": 90,\n \"token_type\": \"Bearer\"\n },\n \"meta\": {\n \"date_time\": \"2022-06-24T19:09:42.963Z\",\n \"name\": \"v1.tokens.authorize\",\n \"uuid\": \"ee6f9feb-dcf8-4421-a6fd-efd6beabdaa9\",\n \"start_timestamp\": 1656097782509,\n \"end_timestamp\": 1656097782963,\n \"execution_time\": 454\n }\n }\n ```\nLooking at this Response, you will see:\n * `access_token`: contains the JWT Access Token string you will use as your Bearer token.\n * `scope`: contains the scopes that this Access Token gives you permissions to access.\n * `expires_in`: contains the length of time before this Access Token will expire, in seconds.\n * `token_type`: verifies that this Access Token should be used as a Bearer token.\n\n## How to use an Access Token after one is generated?\nOnce a new Access Token is obtained, it is used in each call to a DTN API endpoint as a Bearer token in an Authorization Request Header. For example:\n ```\n Header: 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw'\n ```\n\n## Deconstructing the Access Token\nA DTN Access Token carries information within its JWT Body that is available on every API call. By deconstructing the JWT token, our Access Tokens will resemble:\n ```\n {\n \"https://auth.dtn.com/customerId\": \"1234567890Demo\",\n \"https://auth.dtn.com/productCode\": \"DemoApiP\",\n \"https://auth.dtn.com/requesterIp\": \"18.213.174.27\",\n \"https://auth.dtn.com/rps\": \"100\",\n \"https://auth.dtn.com/tier\": \"Basic\",\n \"https://auth.dtn.com/quota\": \"999999\",\n \"iss\": \"https://id.auth.dtn.com/\",\n \"sub\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM@clients\",\n \"aud\": \"https://demo-api.auth.dtn.com/\",\n \"iat\": 1656099068,\n \"exp\": 1656099158,\n \"azp\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM\",\n \"scope\": \"read:demo create:demo update:demo\",\n \"gty\": \"client-credentials\",\n \"permissions\": [\n \"read:demo\",\n \"create:demo\",\n \"update:demo\"\n ]\n }\n ```\n### Description of Claims\n\n | Claim | Type | Description |\n | -----------------------------------| --------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `https://auth.dtn.com/customerId` | String | Custom DTN claim containing the Customer ID found in the DTN Order Management/Salesforce system associated with this token. |\n | `https://auth.dtn.com/productCode` | String | Custom DTN claim containing the Identity product code associated with this token. |\n | `https://auth.dtn.com/requesterIp` | String | Custom DTN claim containing the IP address of the requesting client. |\n | `https://auth.dtn.com/rps` | String | Custom DTN claim containing the maximum rate per second this customer is authorized to utilize. |\n | `https://auth.dtn.com/tier` | String | Custom DTN claim containing the data tier the customer purchased for the requested access. |\n | `https://auth.dtn.com/quota` | String | Custom DTN claim containing the maximum yearly quota the customer purchased for calling DTN endpoints for the specific product. |\n | `iss` | String (URI) | The Security Token Service (STS) that issues and returns the token. If this value is not from `https://id.auth.dtn.com/`, the token should not be considered trusted. |\n | `sub` | String (URI) | The principle about which the token asserts information (the User ID or Client ID within the Identity Provider). A User ID will start with a prefix of `auth0\\|`, while the Client ID will end with the suffix `@clients`. |\n | `aud` | String \\| Array (Strings) (URI \\| [URI, …]) | Identifies the intended recipient(s) of the token – its audience. The token should be rejected if the audience does not contain values expected by the calling application. |\n | `iat` | Number (Timestamp) | “Issued At” indicates when the authentication for this token occurred. |\n | `exp` | Number (Timestamp) | The “expiration time” on or after which the JWT must not be accepted for processing. |\n | `azp` | String | The application/client ID of the client using the token. The application can cat as itself or on behalf of a user. |\n | `gty` | String (Space-delimited) | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific). |\n | `permissions` | Array (Strings) | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific). |\n\n " x-refined-from: - dtn-financial-market-data-openapi.json - dtn-storm-risk-analytics-api-openapi.json