When making API calls, there are four possible identifier_types: assets, tickers, legal_ids, and full_tickers. Which one is the most beneficial depends on your application.
See this tutorial to find asset names and tickers in the CityFALCON system.
The differences between the types
Assets
Assets in the context of the CityFALCON API are specific names of "entities" in our database. They are often a proper or common name of a topic, like Apple Inc, Amazon Echo, Brent Crude Oil, Gross Domestic Product, or Blockchain. On the website, these are the blue names that appear in searches.
In special cases, the API requires so-called slugs instead of these proper or common named assets. The slug requirement only applies to the following concepts, which are really collections of individual entities:
- Topic Classes
- Sectors
- Industries
- Subindustries
- Industry Categories
- Locations
- Events
If you use the Premium version of the API and can retrieve data on these special cases, use these slugs. Note that each of these has a special parameter in the API call and none use the identifier parameter.
Tickers
Tickers are the standard way to identify stocks on an exchange. For example, Apple Inc stock is labelled as AAPL on the NASDAQ exchange. Barclays is BARC on the London Stock Exchange.
For most stocks, they will only be listed on one exchange with one ticker. If you don't know the tickers you need, you can easily find them on the CityFALCON platform.
However, the same sequence of letters can act as tickers for different companies in different countries. For example, consider the sequence of letters that make the ticker AAL. This identifies four companies:
If your ticker is shared by companies in different countries, you will need to use full tickers to avoid irrelevant content.
Full Tickers
These are tickers for specific countries to differentiate between shared ticker sequences, like AAL above that identifies 4 companies in 4 separate countries.
Full tickers are ideal for API programming, since you may be unaware of shared tickers from other countries and waste API calls and returned data on irrelevant content. Changing the approach later might also break your code.
For those two reasons, we recommend using full tickers from the start. To generate the full ticker, simply append an underscore and the country code to the regular ticker. Thus US-issued American Airlines becomes AAL_US while UK-issued Anglo American would be AAL_GB.
Full tickers will not restrict responses to only the named country. AAL_US will return any story for American Airlines in any country. The _US suffix is only intended to differentiate between companies on the CityFALCON database and return American Airlines news instead of Anglo American or Apac Coal news.
If you want to restrict data to specific countries, you will need to use the country_codes parameter, which is available on the Premium version.
Legal IDs
These are numbers associated with legal filings and with the respective regulatory agencies for the company. They are mostly used by large enterprise API applications that already have legal_ids in their database. If you do not already have legal_ids, simply use assets, tickers, or full_tickers. If you do have legal_ids in your system, contact us for more information on using them for CityFALCON.
Application
If you have only stocks with tickers, we recommend using full tickers as the identifier_type, which will allow you to more easily integrate your code. Your URL query string can simply drop the full tickers into place.
If you use simple tickers, check that they are not shared by companies in other countries. If they are, switch to full tickers.
If you have mixed topics - that is, not just stocks but also people, products, untickered private companies, organisations, etc. - you will need to use assets as the identifier_type for the topics that have no tickers.
In this case, you can either
- make two calls, one using tickers for the stocks and one using asset names for the others
- make one call, using asset names for all topics, including tickered stocks