The CityFALCON API is a relatively simple tool that you can use to build your own custom programs based on CityFALCON news, content, and analytics. It's so simple, in fact, that you need no programming background to make calls and retrieve the data via the browser. Any programmatic approaches will require some programming skills though.
Base URL (live)
All endpoints for live API interaction are prefaced by
https://api.cityfalcon.com/v0.2/
API Keys
When you sign up for an account to access the API, you will receive your own key. This key is required every time you make a call to the API to show that you are indeed authorised to receive data from our systems.
To get a key:
- Sign up for an account
- Receive your key and add it to your program
- Make your first test call
- Connect your application
If you are publishing our data, make sure to
- Include attribution if necessary
- Avoid commercial use if disallowed
Your plan will include details on permitted usage and attribution.
Authentication
When you use the live API, you need to authenticate yourself to the CityFALCON servers. If you don't, your API call will simply be rejected.
Authenticate yourself by attaching your API key to the access token parameter:
https://api.cityfalcon.com/v0.2/[endpoint]?[other params]&access_token=[API key]
Endpoints
There are three endpoints and two sub-endpoints. Links take you to our Knowledge Base article for that endpoint.
|
Endpoint |
Description |
|
/stories |
Takes filter parameters and returns an array of stories |
|
/banlist |
|
|
.../articles |
Specifies which article(s) to exclude when returning stories; identified by article UUID |
|
.../domains |
Specifies which domain(s) to exclude when returning stories; identified by string matching |
Headers, Bodies, and URL Queries
With the exception of accepted content type, there is no need to include any headers. All data can be passed through the URL string. Use Accept: application/json for the only required header.
With the exception of /banlist POSTs, there is no need to use request bodies. All parameters can be passed through the URL string.
For /banlist POSTs, use
--header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d '[ban data]'
where ban data is the article or domain to be banned. See the /banlist endpoint article for more information.
All queries will be sent through an HTTPS tunnel and therefore encrypted. There is no need to encrypt your API key or any of the queries.
The Documentation and Playground
See full technical documentation for descriptions on parameters, examples of responses, and to test your API calls. It is GUI-based, so no programming is needed at all. The descriptions of each parameter can help you filter the results.
Click Try It Out to send the API call via the browser and read a sample response. There is also a Request URL line that tells you exactly what string is sent to the API server:
This can be extremely useful when learning to use an API, and it tells you exactly what our API server needs to know to understand your request. Notice that the documentation page uses the sandboxed version, not the live version.