Let us help you connect with Shaping Tomorrow's database and content to create integrations with your own systems and services. Your developers can use our API to do this. The documentation that they will need is below. Feel free to contact us if you need further assistance.
1. Introduction
The Shaping Tomorrow (ST) REST API is designed to allow you to interact with our database. It requires a registered ST user’s login credentials and apiKey, alternatively, you can register a new user and use the new credentials to generate a deviceToken. Using the API key and deviceToken as authentication credentials you can add sources that will be scanned and analyzed by our Athena robot. You can also search our database of future Forecasts and even generate summaries based on text submitted to the API. The output is JSON only except for certain endpoints that will serve up a PDF file when the relevant argument is provided to the method.
2. Rate Limiting
The API is currently limited to one request per second, per device Token.
3. Quick Start Guide
The first thing you need is an API Key, to get one send an email to api@shapingtomorrow.com with the subject line “API Key Request”. Please include details in the email about what you would like to use the API for and what kind of app you’ll be building.
Once you have your API key, you’re ready to begin! The full and most up to date version of the API documentation is available here.
With the API key, you can authenticate a user, or register and then authenticate them. Once you have a deviceToken you can begin sending requests. To authenticate a user send a request containing the user’s email, password, deviceId, and your apiKey to the authentication endpoint located at:
https://api.shapingtomorrow.com/authenticate
The JSON request body should look like this (fields are not case sensitive), the values may also be posted as form fields:
{
"deviceId": "",
"email": "",
"apiKey": "",
"password": ""
}
The response body looks like this:
{
"DEVICETOKEN": "AB12AB12AB12AB12AB12AB12AB12AB12"
}
Once the authentication is successful you need to store the deviceToken locally in your app.
That’s all we require for access, with the apiKey and deviceToken you can now access all the other endpoints.
4. Example of an API request
To list the FORECASTS belonging to a user you would send a GET request to the following endpoint:
https://api.shapingtomorrow.com/list?devicetoken=users_deviceToken&apiKey=your_apiKey
To search the FORECASTS you send a POST request to the same endpoint
https://api.shapingtomorrow.com/list
Form fields:
devicetoken = stored token (REQUIRED)
apiKey = your apiKey (REQUIRED)
q = search query (REQUIRED)
ws = boolean (OPTIONAL)
pdf = boolean (OPTIONAL)
In both of the above cases, you can add ws=true to the request and this will return the output via the WebSummarizer API instead of simply returning a list of FORECASTS. Both methods also allow you to return a PDF instead of JSON. Simply add an argument pdf and set the value to true
Posting data to the API can be done with form fields or a JSON string.
5. Endpoints
For full details about each endpoint please consult the API docs, this section is only intended as a high-level overview.
/authenticate
Handles authentication of user credentials and generates the deviceToken that will be used for subsequent requests to the API.
/register
Allows a new user to be registered with ST, the user will receive a confirmation email and will also be subscribed to our weekly newsletter.
/list
The main forecast listing endpoint allows for both a list of the most recent Forecasts added by the user, as well as a search interface accepting a query parameter. The GET request can include parameters to filter by sector as well as tag. In addition, the results can be sent to WebSummarizer before being returned. An additional argument can also instruct the API to respond with a simple PDF file for offline reading, sharing, etc.
/summary
Allows a block of text to be sent to the WebSummarizer API which will respond with the summary. The output for this endpoint may be a file in PDF format as well as the standard JSON response.
/sources
Add a new source to the database and Athena’s tasklist. The source may be a Twitter @username, Twitter profile URL, Twitter #hashtag, RSS feed URL or a Bing web search. A tagged argument may also be included which will automatically be added to the source. Any Insights and Forecasts found by Athena will also be associated with this tag. Additional methods in this endpoint also allow developers to list out all the sources added by the user, optionally filtered by tag. The GET request will also return data on the amount of content Athena is gathering. Additionally, this endpoint can be used to delete a source belonging to the authenticated user from the database
/sectors
List the sectors from the database with title and ID. The ID can be used with the SECTOR argument in the list endpoint to output Forecasts by sector. Post a sector ID and get back the TITLE.
/tags
List the tags belonging to sources added by the authenticated user. The tag can be used to output a list of forecasts by posting the tag to the list endpoint. This endpoint also accepts a ‘typeahead’ argument which can be used to search based on initial letters, eg. dro would list drones, drown, etc. This endpoint can also be used to remove a user’s tag should that be required.
6. Questions, problems or comments?
We welcome feedback on our API and documentation, and our team is also more than willing to assist you in understanding how everything works. We may even be willing to create new endpoints that are not currently included if you feel that there is the functionality you would like to include in your app. To get in touch, contact us via email, Twitter or telephone:
Email: api@shapingtomorrow.com
Telephone: +44 1273 832221