API Formation, Authentication, XSL Transforms, Suggested Sequence of Calls, Symbol Formats, Tips and Tricks
API Formation
A Recognia API call can be issued in the form of a GET or a POST. For the purposes of this document we will use the GET formation in order to simplify the presentation of the API. However, all comments apply to the use of POST in place of GET.
The formation of a Recognia API call is the construction of a URL. Recognia API calls have the form:
[server]/[command]?[parameters][authentication]
for example
https://api.recognia.com/api/securitychart?eid=RCvpPOAAAH3QA-gABAAC_AAD6CYg&zom=trend&uid=example&cid=100&pwd=1234
This example can be broken up as follows:
[server] = https://api.recognia.com/api [command] = securitychart [parameters] = eid=RCvpPOAAAH3QA-gABAAC_AAD6CYg&zom=trend [authentication] = uid=example&cid=100&pwd=1234
The server is the address of the Recognia API.
The command is the Recognia API command that you wish to use. The API commands are discussed in more detail in the following sections.
The parameters are specific to the API call. Parameters are separated by an ampersand (&).
The authentication can be one of two types: User ID or Transaction ID. Both are separated from the parameters using an ampersand (&).
The authentication and parameters can appear in any order and can be intermingled, but the Recognia convention is to group the authentication information together as the last element of the API call URL.
Authentication
Every call into the API requires that the calling user be authenticated. The API supports two methods of authentication:
a client id/user id/password triplet
a transaction id
When calling the API, you can supply the cid (client id), uid (user id), and pwd (password) parameters to the call. These values are checked against the database and if valid the call is processed.
Each Recognia Customer has a unique client id. User id values will be assigned based on the needs of the customer. For some customers they will require only two user ids - one for administration and the other for non-administration activities (such as retrieving technical events).
Other customers may require a unique user id for each of their users, or sub-sets of their users. Recognia can provide the customers with access to the administration commands that permit customers to add, change or remove users as required. Please note that user ids are case sensitive.
In the <header> section of the XML returned is a field called <transaction>. This field has a "value" attribute which contains a unique id for the calling client/user and the originating IP address. Subsequent calls to the API can make use of the tid parameter with this <transaction> value, instead of having to re-supply the client id/user id/password triplet.
The tid parameter can be used only if the IP address has not changed and the subsequent call is made within 48 hours of a call that provided the transaction id. Note that each call made using a specific Transaction Id refreshes the timer. Otherwise the client id/user id/password triplet must be supplied.
There is a performance gain in using a transaction id instead of the triplet.
Transaction ID Types
The API supports three different methods for obtaining a transaction id. You can specify which type
of transaction id you wish the API to return by adding a
The API supports three different methods for obtaining a transaction id. You can specify which type of transaction id you wish the API to return by adding a aut parameter to any API call. The value of the aut parameter determines the type of authentication id returned with your call.
| aut | Meaning |
|---|---|
| 0 | This tells the API to not generate or return a transaction id. The user is still authenticated, but no time is spent generating a transaction id. If all API calls you make use the cid/uid/pwd method of authentication then adding aut=0 to your calls will result in a small performance improvement. |
| 1 |
Charting API access only
This id expires after 48 hours regardless of the number of times it is used. This ID is typically used when placing API calls within a webpage that is then served to the user. For example, <img src="https://api.recognia.com/api/securitychart?iid=308931401&eid=USvvWSAAlthwAzgABAACAAAD6CRg&tid=Lvm6vgZE9HPMyvBAHTcqjjr3tKELB23%2BXoQOwWrZBx9Dg5%2FSp6whA5biurMvTRbWZLjmez1Rd%2Fx0RitZT0h6s9v5gDbSe%2FStz3n97uGMVpRUPgLpWXpKJuqF26T6uqrY" /> |
| 2 |
Full API access
This id expires after 48 hours regardless of the number of times it is used. The ID will be validated against the IP Address of the system making the call. It is therefore important the calls be made from the same computer that generated the ID. |
XSL Transforms
The API supports applying XSL Transforms to the results from an API call. To apply a transform you must have registered the XSLT with the API. Refer to the API functions xsltadd, xsltupdate, xsltlist.
Once the XSLT is registered you can apply it to a return by adding the xst parameter to the call. For example api.recognia.com/api/exchanges?xst=pretty_list.
You can supply parameters to the XSLT by adding the xpm parameter to the call. You separate the parameter name and value with a colon. You separate multiple parameters using a comma. For example api.recognia.com/api/exchanges?xst=pretty_list&xpm=colour:blue,order:descending.
You can apply more than one transform by adding additional transforms to the xst parameter, separating each with a colon. The transforms are applied in the order they are listed. For example api.recognia.com/api/exchanges?xst=pretty_list:as_html&xpm=colour:blue,order:descending. Note that all transforms are passed all parameters.
Recognia currently uses LibXSLT, version 1.1.2, for XSL transforms.
Suggested Sequence of Calls to the API
Use a secure HTTPS POST to call the gettransaction API call using your client id, admin user id, and password values. This encrypts the password in the request. Extract the "value" attribute of the <transaction> tag from the returned XML and cache this for a period of time (e.g. 6 hours). While it is recommended that a dedicated gettransaction call be used to get a transaction ID, any command will return a transaction ID that can be used for subsequent API calls.
Plain HTTP can be used for subsequent calls that specify the transaction ID instead of the user ID and password. This provides a performance gain over secure HTTPS.
It is recommended that an HTTP GET be used to call commands that retrieve information, while an HTTP POST is used for commands that modify information (e.g. to change user preferences or upload an XSLT).
Failed Authentication
If the user cannot be authenticated, an HTTP 403 is returned. In addition, the <header> block of the returned XML will contain an attribute value of "false" for the <authenticated> tag.
Commands Issued on Behalf of Another User
Any command can be issued on behalf of another user by the administrator user for the client. To do this, use the administrator user's transaction id or user ID and password. Add an additional parameter cui, which contains the ID for the user for whom the call is being made. This is useful when using a cached administrator transaction ID in order to make calls to update alerts or other user preferences for a specific user ID.
Retrieving Technical Events
To build an "Event Lookup" page listing recent events for a specific stock, the eventsforeach call is often used to pull back four event lists simultaneously, one for each of the four event classes. Alternatively, the events call can be used to pull a single list of events for the instrument, such as a chronological list. The events call is also used to create the results page for a "Stock Screener" search.
The securitychart call is used to display a chart for a particular stock, usually for a particular event or set of events. A thumbnail size is available in addition to the larger sizes. Alternatively the eventmarkup call will provide data points that can be used to annotate a third-party chart with the pattern lines.
The education call is used to retrieve educational material about a particular event type or glossary term. The eventtypes call is used to pull back the list of available event types in order to build a select list for a screener form, or to build a glossary list. The information provided by these two calls does not change often, therefore the output may be cached for a limited period time (e.g. 6 hours).
Symbol Formats
A specific instrument may be requested in an API call by specifying a symbol and exchange combination, or by specifying the Recognia ID for the instrument. The instrument ID provides a slight performance gain, therefore it is recommended that the symbol and exchange combination be used to make the first call for the instrument, and the instrument ID be used if there are subsequent calls for the instrument.
When an API call returns an <instrument> block, the instrument ID can be found in the child <id> tag. For subsequent calls, the instrument ID can be used as the value for the
The Recognia API supports multiple symbol formats, therefore there are multiple parameters that can be used to specify the symbol depending on the format that is most convenient for the implementation. See Symbol Formats for a list of the currently supported symbol formats. Also, there are multiple symbol tags returned in the <instrument> block in order that you may select the appropriate symbol format for the implementation.
The exchange for the symbol may be specified using the
Tips and Tricks
Do not rely on Event IDs to stay constant. This may be important if you allow the user to bookmark a link to a chart. At some point in the future the chart link may no longer be valid and may result in the page being incorrectly displayed or have missing information.
Event Type Ids should not be used to group Events. Do not assume that all eti >= 1000 are Indicators and Oscillators.
The Instrument Symbol (e.g. cms to specify the 'common' symbol) and Exchange (exc) can be used together or separately. If used together they can specify a specific symbol on a specific exchange. This is important when a symbol is duplicated across multiple exchanges. In most circumstances this will only occur if an instrument is cross-listed on two country exchanges. If the Exchange is not specified then all matching symbols, for all exchanges, will be returned. If the symbol is not specified then all events (subject to other criteria) for the specified Exchange will be returned.
In order to retrieve events associated with indices you must either not specify the Exchange or you must use INDEX for the Exchange. In addition, you must specify the ity criteria as ity:eq:I.
When presenting Indicators and Oscillators the <event_type_specific> block of the <event> has additional information that may be required in order to present the event to an end user correctly.
When the instrument's close price reaches a pattern's target price range on the same day that the pattern was identified (this happens when the price spikes dramatically on the day of the event), this means that the expected move is already taken. The user application should provide a message to the user when such events are listed. This condition can be determined by checking the target_price_range/close_position tag of the <event> block. When the value of this tag is WITHIN or BEYOND then the following message should be displayed: "The instrument reached the target price on the same day the pattern was confirmed. Accepted principles of technical analysis suggest that no further price movement should be attributed to this pattern."