APIs are a wonder for anyone that wants to automate information processing, as they allow systems to talk to each other and handle all of the data transfer before being loaded into local processing pipelines. Typically, the benefits of high-value APIs in the financial world are restricted to businesses and rich traders. 

Over time, we have seen strong demand for our API from technically inclined traders and investors. We now offer a Personal Starter API plan that starts at just $40 per month when purchasing an annual subscription. Academia, non-profits, and health care workers receive a 50% discount on the price, taking it as low as $20/month on an annual contract.  With our personal API plan, non-enterprise users can now benefit from automating their news and financial content flows for themselves. 

In the initial phases the sign up process is semi-manual, and to justify the workload, we are requiring users sign up for at least 6 months. In future, the process will be fully automated, and quarterly licenses will become available.

In this post, we will look at how the CityFALCON API can be used in non-enterprise cases and give a little background on the API.  If you are looking for the enterprise version of our API, head here.  

 

Why Use CityFALCON’s Data

As with our web-based product, the API delivers timestamps, headlines, and story descriptions after their journey through our natural language processing (NLP) pipeline. The pipeline journey captures content from 5000+ pre-vetted sources and then separates and clusters the content into useable topics and categories, like securities, companies, cryptocurrencies, commodities, products, people, and hundreds of thousands of other topics. To get an idea of the extent of the coverage, browse the Topics and Asset Classes section of our Directory. Sectors and Locations content will be available for the premium version of the Personal API plan in the future.

Our content association is much more powerful than just a keyword search, with associated data and a CityFALCON score. For example, using just the identifier Tesla, the stories you receive will contain the company name plus the associated tickers, here TSLA US. For each story, you also get our proprietary CityFALCON relevance score, a duplicate count (one indicator of popularity), and information related to the source, such as whether it requires registration or locks its content behind a paywall. Source type is also included, so you can restrict information to only major publications or research firms.

To refine your search, our API accepts many filters, including on domains, languages, a minimum CityFALCON score, and time period filters. We process all of this on the backend so your system does not have to deal with foreign languages, low relevance content, or throwing away content that is too old. 

We also have an active team of financial analysts that vets all of the publications before they are added to our systems and ensures the aforementioned 300,000+ topics are accurately processed by our machine learning system. This protects users from low-quality sources flooding their feeds. All of that value is created under the hood of the CityFALCON platform, and the resulting output is easy to take advantage of.

Here you can see the JSON for a story from an API call for content related to Apple, using the search term “Apple Inc” (though “AAPL” or “AAPL_US” could just as easily be used):

 

NLP-driven Real-time News in a Fair Distribution Framework

With the Personal Starter Plan, there is no artificial delay imposed from our end. Once our systems are finished processing the content, it is available to be served for API calls. You won’t have to worry about falling 30 minutes behind richer clients and corporations, because we deliver as soon as the data is prepared – our mission, after all, is to democratise access to financial content.

Nor do we restrict the publications for our lower-priced plans, as some companies may do. If a publication is part of the 5000-strong sources available on CityFALCON, the usual content delivered through our API service will be delivered to all levels. The only exceptions are Twitter content and premium full-text content provided under our Gold plan, neither of which are available for any of the API levels. Twitter and full-text content require licenses directly from the providers. 

At the Personal Starter level, you are also entitled to 10,000 API calls per month. This comfortably allows one call every five minutes for the entirety of the month, assuming you use the API 24 hours a day, 7 days a week. If you are only making calls for 12 hours a day, your frequency could increase to every 2.5 minutes. This is sufficient even for active traders, since publications and news sources are not adding entirely new content every 2 minutes. For most cases, a frequency of two or three times an hour is enough.

On top of the total number of calls, each call can accept 50 parameters (i.e., tickers or topics), and each response can carry up to 100 stories. So unless you are extremely diversified, you can usually fit your entire portfolio and any related topics into a single call. With up to 100 stories in each response,  there is plenty to parse and feed into your own NLP algorithms. 

Our future Personal Starter Plus plan will allow up to 100,000 calls per month instead of 10,000, plus greater search capabilities, more intensive topics, and Similar Story Groupings. 100,000 calls is likely sufficient for almost any non-commercial task, while Similar Story Groupings will help reduce redundancy in returned content.

 

Straightforward Integration

CityFALCON’s API is very user-friendly, even for those who are not very technical. There are a few simple GET calls and optional POST or DELETE calls. 

The main GET to retrieve stories data is implemented entirely through a query-string in the URL, so there are no extra headers or other information to send. Even the authentication key is sent via URL. Of course, this must be sent through an encrypted tunnel, but all that security is handled for you through the protocol, as long as you make HTTPS calls. It’s so simple, you can test calls in the browser URL bar if you wanted to.

The response is a simple JSON block, which you can parse up in whatever language you’re using to make the calls. We do not automatically generate code wrappers for you, so you will need to set up the calls and handle the JSON in whatever language you prefer. However, since the entire GET is via a URL-string, simple string concatenation works perfectly fine for the request. Plenty of languages have open libraries for parsing JSON and managing call frequency.

You can find tutorials on the mechanics of the API in our Knowledge Base or in the basic documentation. Due to our very small team, we are unable to give much advice on how to integrate the API with your personal systems. We can only solve issues that arise on the CityFALCON side of the exchange.

 

Valuable Potential Use Cases

“Why use an API at all, when there is a brilliant web platform already?” That is a completely valid question. And we appreciate the compliment on the web platform.

One good reason to use the API is if you already have your own proprietary trading/investing dashboard and want to integrate news. Rather than toggling between a web browser to view CityFALCON.com and your dashboard, you could integrate financial content straight into your dashboard. That way, as you make trades or investments, you can programmatically update your integrated news feed. You’ll never forget, and depending on your level of programming skills, never even notice.

Another good reason to use our financial news and content API is when you have your own natural language understanding (NLU) system. This is certainly a much loftier goal. However, it is not out of the question. Perhaps you track specific keywords in headlines and article descriptions related to your portfolio’s assets. CityFALCON aggregates the content from more than 5000 verified sources and clusters it into useful topics (companies, sectors, people, etc.). Then you can focus your NLU algorithm on just that content rather than wading through all the irrelevant content floating around the web. Once your algorithm detects specific terms or goals, you can trigger an alert so you can start researching more deeply.

At least one more reason to try the Personal Starter API plan is to gather and store data locally for more research specifically on that data. This approach often appears in academia, but traders and investors might want to do this to backtest or develop new strategies, too. The web and smartphone app platforms are optimised for human eyes, but are hard for computers to work with. Instead of scraping CityFALCON and dealing with all the changes – not to mention violating the CityFALCON Terms of Service – you can simply grab the information from the API. Then you can store it locally and process it however you like.

 

Some Terms and Conditions to Using the CityFALCON API

If you’d like the legal info, visit our API Terms and Conditions page.

We are a reasonable company and we expect our customers to act in a reasonable way. This implies we have two main conditions to adhere to when using the API: attribute credit and do not scrape. Please also note that we provide the Personal Starter API plan for non-commercial use only.

If you publish anything derived from the content we provide, please provide credit to the publishers and author(s), including a link. We only have data because publishers work hard to manage, aggregate, and fund journalists, investigators, content creators, and organisations. Without these companies and their people, there would be little coverage or very centrally-controlled coverage. But their models only work if they receive money. So please credit and link to them. If you are using the API as an academic to publish papers, naturally you need to cite your sources anyway. 

Whether you publish or not, please do not scrape the provided URLs for content in any way that violates the publisher’s Terms and Conditions. The API is designed to help you find the content, not provide it in full. If you would like full-text articles without visiting the publisher sites, check out our Gold Premium subscription (not API-based). 

If you follow these two points, there should not be any issues. Our providers are happy, we’re happy, you’re happy.

 

Get Started in a Few Easy Steps

Getting set up is just a few easy steps. Until we automate the onboarding process, simply contact us and you’ll be well on your way to incorporating real-time news from more than 5,000 sources with the added benefit of a multimillion-dollar fintech company’s proprietary machine-learning algorithms doing most of the heavy lifting of NLP and content sorting. You just need to call up the tickers or topic names, receive the news, and focus on trading or investing in the markets.

Because of the amount of data we deliver to you and the semi-manual onboarding process, all Personal Starter API customers must subscribe for at least 6 months. Once the process is fully automated, the time and resources for creating subscriptions will be negligible and we can open quarterly pricing:

 

Subscriber Type Minimum Commitment Cost
Academia, healthcare, non-profit 6 months $150 (half year), $240 (full year)
Others 6 months $300 (half year), $480 (full year)

 

While as of yet unreleased, this chart compares the Personal Starter regular and premium versions:

Regular versus Premium Personal Licenses

Personal Starter Personal Starter Plus
Number of API calls 10k/month 100k/month
Coverage Search by ticker or topic on 300k+ topics and securities, except Locations, Sectors, and grouped Asset Classes (e.g., cryptocurrencies, people, etc.) Personal Starter plus:
Search and results for Sectors, Locations, and grouped Asset Classes
Grouping of Similar Stories
Proprietary CityFALCON Score
Full Price (billed semi-annually) $50/month $100/month

 

A Few Frequently Asked Questions (FAQs)

1. How much historical data can I retrieve?

You can retrieve up to 30 days of historical data. If you want to retrieve more, see our Historical Data Sets product, which will provide CSV-formatted historical data up to 5 years old. With such archival data, we do not openly provide it on the API to ensure better API performance.  We will launch the Historical Data Sets product later in the year.

2. How can I claim discounts for certain groups, like students and healthcare workers?

If you sign up with a verifiable organisation or university email or by providing a copy of identification that identifies you as a member of an eligible group.

3. Do you offer a trial before purchase?

Unfortunately for the Personal API we cannot offer a trial period. This is mainly because of the manual onboarding work required.  Once we finish our self-service portal, you will be able to trial the API before buying.  

Meanwhile, we can refund your purchase within 15 days if you use less than 100 API calls. Moreover, the data for the API and the website come from the same CityFALCON system. We do offer 7-day trials of Silver plans and a free Basic plan, with features outlined on our Subscription Pricing page. You will receive similar content from the API as the website, so you could try out CityFALCON through the website first (excluding certain high-value, high-cost features like sentiment, summarisation, and full-text articles).

4. Can I upgrade from a Personal plan to get more features?

Of course. The process is still manual for now, so please contact us if you want to upgrade.

5. How do you define “Personal Use”?

Personal use entails applications that are not commercial in nature. If the application generates revenue/users/website engagement for you, it is probably commercial. However, other applications can still fall outside the “personal use” category. If you publish CityFALCON data on a personal or academic blog, such as pasting the JSON response, this is non-personal use and thus disallowed. Derivative works may be allowed, but only if their main purpose is not to drive traffic or generate revenue. See this Knowledge Base article for more details. If in doubt, you may contact us.