Symbols
Each symbol or search pattern allows you to access one or more market quotes. Some API’s can take multiple symbols when separated by commas.
IMPORTANT: Special characters will need to be URLEncoded when making the requests.
To query for 3 different symbols at once e.g. @LE@1,@LE@2,@LE@3 – you would need to do /markets/symbols/@LE@1%2C@LE@2%2C@LE@3/ quotes – note how the comma values are URL encoded as %2C.
To include wild card searches such as @LE’## 3 – you would need to do /markets/symbols/%40LE%60%23%23%203/quotes – note the URL encoding of backquote ` to %60 and the hash # to %23 and the space to %20.
The following table shows some examples of search patterns for futures options:
| Pattern | Description |
|---|---|
| C`##C6### 10 | Selects calls of the first 10 contracts of Corn futures options with a strike price between 600 and 699. |
| C`##<CP>68## 20 | Selects calls and puts of the first 20 contracts of Corn futures options with a strike price between 680 and 689. |
Following are some more generic examples of search patterns:
| Pattern | Description |
|---|---|
| @C@1 | Selects the first electronic Corn contract. |
| @C@5 | Selects the fifth electronic Corn contract. |
| @C`## | Selects all electronic Corn contracts. |
| @S`## 3 | Selects first three electronic Soybean contracts (there is a space between # and 3). |
| @C`##,@S`##,@W`## | Selects all the electronic Corn, Soybean, and Wheat contracts. |
As some of the examples above suggests, there is a way to limit the number of symbols returned by a search pattern by explicitly specifying a quantifier. The quantifier is an integer number separated by a space after the search pattern and can be specified for each pattern as in this example:
*B*L 2,NG`## 5,C@3 3
Symbol and Market
Since there are symbols that can be differentiated only by the market, a request for a given symbol may return multiple entries, one for each market. To avoid this situation a symbol can be fully qualified in the request by explicitly indicating the market and symbol as in “NYS:IBM” or the vendor, market and symbol such as “DTN:NYS:IBM”.
For most of the cases, the Market and Vendor input fields are optional and are rarely needed to refine the request for symbols within a specific Market and/or Vendor. Only one Market and/or Vendor can be entered and they are overridden when entering a fully qualified symbol notation.
A history request for expired symbols requires the explicit specification of the market using any valid method.
These parameters are needed when the user is registered for accessing same symbol from two different sources, which in practice is not common. A user permitted to obtain quotes from DTN and other vendors, by default, will see DTN information unless explicitly sets the desired Vendor parameter to something different.
Search Patterns
The DTN Quote Server and ProphetX client use string pattern matching in some places to make a user’s or administrator’s job easier. Powerful useful patterns can be expressed with a small wildcard expression.
Patterns are described by some combination of special and normal characters. By default, patterns that consist of all lowercase or all uppercase letters are not case sensitive (AB will match AB, ab, Ab, and aB). Patterns that consist of mixed cases are case sensitive (Ab will match only Ab).
Special Characters
| Character | Definition |
|---|---|
| ? | Match a single character. |
| <set> | Match any single character contained in the set. For example, <0-2> will match with 0, 1, and 2. |
| {set} | Match a substring composed of one or more of the characters described by the set. |
| # | Match one numeric character. (This is equivalent to <0-9>.) |
| ` (backquote) | Match one month code letter. (Month code letters are FGHJKMNQUVXZ, so the backquote is equivalent to <FGHJKMNQUVXZ>.) |
| ‘ (quote) | Match one second year month code letter. (Second year month code letters are ABCDEILOPRST, so the quote is equivalent to <ABCDEILOPRST>.) |
| ” (doublequote) | Match one first or second year month code letter. (doublequote is equivalent to <ABCDEFGHIJKLMNOPQRSTUVXZ>, or any letter except W and Y). |
| * | Match a substring composed of one or more characters. |
| ^ | Use a carat as the first character of your pattern to make a case-sensitive match. (The carat is needed only if your pattern consists of all lowercase or all uppercase letters — for example, ABC or abc. By default, patterns containing mixed uppercase and lowercase letters are automatically treated as case sensitive.) |
| \ | The escape character. This removes the special significance of the next character, allowing you to search for it as itself. For example, \# matches the character # rather than any single numeric character. To search for the escape character (backslash) itself, enter \\. |
| & | The ampersand character. The & represents itself with sets. Outside of sets it is ignored, Unless it occurs within a fixed text substring of the pattern. In that case, it has the effect of breaking fixed substrings into two substrings for the purpose of matched pattern substitution. This is used in regular expression reformatting and in symbol translation. See the XLate documentation for examples of this usage. |
Character Set Descriptions
| ^ | If the first character of a set is carat, then the opposite of set will be matched — that is, everything except the pattern described by the set. |
| A | A single character represents itself. |
| A-C | Two characters separated by a hyphen describe themselves and the range of characters between them. For example, A-C will match A, a, B, b, C, and c. |
| – | A hyphen at the beginning of the set (but after the ^ if there is one) represents itself. |
| \ | A backslash escapes the next character’s special meaning. It may be used to add any character to the set, including \ and > and }. |
Fixed Substrings
Any substring of the pattern which is not a special character or a character set is considered a fixed substring of the pattern.
Limits
The pattern can only contain ASCII 1-127.
A pattern can have up to 10 components, where a component is either a fixed string, a # or * or ?, or a {set}. Multiple adjacent # or * or ? characters are considered a single component.
The sum of the lengths of the fixed strings in the pattern is limited to about 200 characters (or less if sets are used).
Wildcard Examples
| Pattern | Example Matches |
|---|---|
| cat | Matches cat, CAT, Cat, cAt … |
| ^cat | Matches cat |
| cat* | Matches cat, cattail, catawba … |
| *cat | Matches cat, deadcat … |
| ca*l | Matches call, cattail … |
| c*#4P | Matches cat34P, c99xx234P, and c04P, but does not match c4p, c4P, or c04p |
| c*{0-9}4p | Matches cat34p, c99xx234P, c8384204P |
| <a-cfr-t> | Matches a A b B c C f F r R s S t T |
| {a-cfr-t} | Matches caT, bat, bar, Barf, art, bass … |
| SP`#{0-9}<CP> | Matches SPZ350C and other standard S&P options, but will not match SPZ4. |
Keyword Search
Symbols can be found using keywords found in the description or other metadata associated with the symbol using the searchText query parameter for /markets/symbols. This operation works best for finding symbols based on known meta-data fields such as location, provider, or grades. Please note the types of meta-data stored with symbols is different for different categories of symbols. Also the descriptions and meta-data associated with symbols does change from time to time which can affect the results.
By default, one or more keywords must be found for a symbol to match.
Example: dtn grain bids 50623 will find all Grain Bid symbols from the 50623 zip code.
Optionally multiple keywords can be combined with “or” to match either word.
Example: Butter or cheese
The word “not” excludes the next keyword.
Example: Butter or cheese not "cash settled"
Parenthesis can be used to group portions of the search.
Example: (Cheese spot) or (Butter not 2020)