What is the purpose of GroupId in the instruments resource?
GroupId indicates that the instrument in a search result belongs to a group of similar instruments. GroupId is meant as an aid to user interfaces which want to group the instruments returned from a keyword search into logical clusters for better visual representation.
Instruments are grouped when they refer to the same underlying entity. Stocks, Bonds, CFDs and Stock Options are grouped in this way if they are issued by the same issuer or if they derive from an instrument issued by that issuer. "Apple Inc." is an example of such an entity and the Apple stock (both primary and secondary listing), CFDs on the Apple stock, Options on the Apple Stock and Bonds issued by Apple Inc are therefore grouped together. For commodities, the underlying commodity is the common denominator. "Wheat" is an example of such an underlying commodity and Futures on Wheat, Options on Futures on Wheat and CFDs on Futures on Wheat are all grouped by virtue of the underlying commodity. FX and FX Options, are grouped by underlying currency cross. Finally Stock Indices and CFDs on Stock Indices are grouped by underlying Stock Index.
As an example, if you search for the keyword “Apple” the returned list will include roughly 40 entries including Stocks, CFDs, Options and Bonds. The first 38 of these will have the same GroupId because they all relate to the principal company “Apple Inc”. The remaining two entries have different GroupIds, because they represent instruments which do not relate to Apple Inc, in this case the stock on “Apple Hospitality REIT Inc.”,“Applegreen Plc”.