If you've never used an API before, see our API Primer to get started.
This article will explain how to use the Stories endpoint to retrieve content from our API. There are up to 11 parameters you can send to our servers, most of which are optional or have default values. You will receive up to 24 fields per story per response, though not all fields are always informational (there may be no images for example).
This tutorial is geared towards those who are newer to APIs and don't know much about programming. If you're already familiar with APIs, you can go straight to our technical documentation page.
The endpoint can be reached via the following URLs:
- for sandboxed testing version:
https://sandbox-api.cityfalcon.com/v0.2/stories
- for the live version (you will need authentication):
https://api.cityfalcon.com/v0.2/stories
The Parameters
These are the options you send to the API service to request specific stories. Most of them are pretty straightforward, and a full list along with their descriptions can be found on the documentation page.
Say you want to see news for Apple, Microsoft, and Amazon. These are all public companies, so you can simply use their respective tickers (AAPL, MSFT, AMZN).
Set your identifier_type to tickers and the identifiers to aapl,msft,amzn. In your URL string, it should look like this
identifier_type=tickers&identifiers=aapl,msft,amzn
Make sure you don't have spaces in the URL, as spaces are not transmitted over HTTP.
You can add any supported parameter you want this way. For GET calls on the Stories endpoint, you only need three pieces of information:
- identifier_type
- identifiers
- access_token
Everything else is optional, but we highly recommend including other parameters for better data management. You can see a list of slugs for the Premium API sector, asset class, and other filters here.
The Stories Response
Once you've fired off the API call, you wait until you receive the response. It may take a second depending on your internet connection, but you should expect something within 1-2 seconds.
What comes back from the API call is a string of text in JSON dictionary format. Some browsers automatically format this text for easier reading. If you are using your own program, you will need to parse, format, and print the JSON yourself.
Regardless of your call method (browser or own code), you will receive the same information. Every returned story or tweet will include up to 24 pieces of information. Included in every response you will see the content's unique identification number (for our database), the source publication and a URL, a title, and analytics like CityFALCON Score and NLU tags. If available, you'll also see information like description, summary, image URLs, author, and follower count (for tweets only, of course).
Full-Text Search Parameter (Premium only)
If you don't want to use tickers or you want information on a complex topic, you can use our search_query parameter. Note that this requires a minimum subscription level and is not available to all subscribers.
Since you will need to use spaces here, use the hexcode for spaces (%20) in the URL string. The search query "Oil prices and global tensions" should be written like this:
base URL + /stories?search_query=oil%20prices%20and%20global%20tensions