Shaping Tomorrow API

Version 1.0

Resources:

webtext GET /webtext

Get a webtext by ID number (internal use only!)

apiKey is required for all requests.

The returned JSON body looks like this:
[
   {
         "TITLE" : "tag",
         "TEXT" : ''
   }
]

get
Returns the title and text of a webtext based on the supplied ID number
Arguments:
optional numeric webtextid
The ID number of the webtext

tags DELETE GET /tags

Get all the tags attached to sources belonging to the authenticated user. To add a new one, simply submit it in the relevant argument when adding a source.

deviceToken and apiKey are required for all requests.

The returned JSON body looks like this:
[
   {
         "TITLE" : "tag"
   }
]

get
Returns all the tags added to sources by the authenticated user
Arguments:
optional string typeahead
Use this argument in conjunction with a typeahead to add letters to search on, the SQL will do a wildcard search starting with the letter(s) entered. A more efficient way to do this would be to download the entire list of tags when the app loads and use them in a native typeahead. If you do so, you must remember to update the list periodically and especially after sources with new tags are added.

delete
Remove a tag from the database
Arguments:
required string tag
Tag to remove, you may only remove tags belonging to the authenticated user. Responds with a JSON string containing a field called 'MESSAGE' with the value 'Success'

summary POST /summary

Post some text to the WebSummarizer API and get a JSON string or PDF document with the summary.

deviceToken and apiKey are required for all requests.

The JSON response body looks like this:
{ 
   Keywords: [],
   ShortSummary: [],
   KeywordRanks: [],
   FullSummary: [],
   Type: "",
   Title: "" 
}

post
Submit a block of text to the WebSummarizer API.
Arguments:
required string inputText
The text block to submit to WebSummarizer
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string deviceToken
The deviceToken stored locally after authentication
optional boolean pdf (default: false)
If you wish the API to return the output as a PDF instead of JSON then set this argument to 'true'

sources DELETE POST GET /sources

Add (POST) and list (GET) sources from the database, you may also use DELETE to remove a source.

deviceToken and apiKey are required for all requests.

get
Lists the most recent 1000 sources added by the authenticated user. The JSON will contain fields for TITLE and ID, along with various other fields including some statistics from Athena's log about how much data she is gathering. The ID can also be used with a DELETE request to remove a source from the database.

The JSON response body looks like this:
[
   {
      "TOTAL_INSIGHTS": 6,
      "RSS": "https://www.google.co.uk/alerts/feeds/18063037792485323000/8829033790769206021",
      "TOTAL_RUNS": 1,
      "TWITTERSEARCH": "",
      "TOTAL_INDICATORS": 15,
      "TITLE": "Google Alert - \"smart cities\" OR \"smart city\"",
      "ID": 508784,
      "SEARCHEXPRESSION": "",
      "LAST_RUN": "July, 11 2015 01:53:00",
      "TOTAL_ERRORS": 0,
      "TWITTER": ""
   },
   {
      "TOTAL_INSIGHTS": 42,
      "RSS": "",
      "TOTAL_RUNS": 19,
      "TWITTERSEARCH": "",
      "TOTAL_INDICATORS": 76,
      "TITLE": "Steve Rosenbush",
      "ID": 445297,
      "SEARCHEXPRESSION": "",
      "LAST_RUN": "July, 17 2015 02:35:00",
      "TOTAL_ERRORS": 0,
      "TWITTER": "Steve_Rosenbush"
   }
]
Arguments:
optional string tag
A tag with which to filter the sources list
optional numeric sourceid
The ID number of a single source if you only wish to retrieve the data for one of them

delete
Remove a source from the database
Arguments:
required numeric id
ID number of the user's source to remove, you may only remove sources belonging to the authenticated user. Responds with a JSON string containing a field called 'MESSAGE' with the value 'Success'

post
Submit a source: @twitter_user, #twitter_search, RSS feed URL or Bing search query. The omniAdd function will figure out what it is and add the source to Athena's workload. She will then begin gathering data from the sources per the schedule listed below. The response will be a JSON object with 'Success' and 'Error' fields. If the error field is empty the request was successful, the success field will confirm that the input was correctly added to the database.

The JSON response body looks like this:
{
   "SUCCESS": "",
   "STREAM": "",
   "ERROR": "",
   "PROCESSSTREAM": ""
}
Schedule:
RSS Feeds - Saturday
Bing searches - Sunday
Tweets - Monday, Wednesday and Friday
Twitter Searches - Tuesday and Thursday
Arguments:
required string omniSource
Post a @twitter_user, #twitter_search, RSS feed or Bing search query.
optional string tag
A single tag to assign to the source when it is added, you can use the GET method in the tags endpoint if you wish to create a typeahead or list of tags for the user to select from. Please see the tags endpoint for further information. New tags may also be added by submitting a string in this argument.
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string deviceToken
The deviceToken stored locally after authentication

sectors POST GET /sectors

List the sectors from the database. Please note that not all Forecasts will have sectors assigned.

deviceToken and apiKey are required for all requests.

get
Get a list of sectors from the database, returned field names are TITLE and ID. The ID can be used in the list endpoint to output a list of Forecasts by sector. The JSON output for the response body looks like this:
[
   {
      "TITLE" : "title",
      "ID" : id
   }
]

post
Get a sector title by posting the ID. The JSON output for the response body looks like this:
[
   {
      "TITLE" : "title"
   }
]
Arguments:
required numeric sector (default: false)
Sector ID number to return the title for.
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string deviceToken
The deviceToken stored locally after authentication

register POST /register

Registers a new user with Shaping Tomorrow, doing so gives them access to our website and allows your app to authenticate requests for them. Users will also receive an email from Shaping Tomorrow confirming their registration and be added to our weekly Newsletter email.

Only the apiKey is required for requests to this endpoint.

post
Submit user details to register with Shaping Tomorrow, your app MUST validate the presence of the required fields before submission. It is also recommended that you validate the email address before allowing the API request to be made. An invalid email will cause the resgiatration to fail. The response will be a JSON string containing fields for 'SUCCESS' and 'ERROR'. Either field will be filled in but never both fields. Once the registration is successful your app may submit the same email and password to the authenticate endpoint to generate the deviceToken.

The JSON response body looks like this:
{
   "SUCCESS": "",
   "ERROR": ""
}
Success messages:
  • Registration successful
  • That account has been undeleted
Error messages:
  • There was a problem registering the user
  • That email address is already registered
  • Response from the registration server was not valid JSON
Arguments:
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string fname
First name
required string sname
Last name
required string email
Email address
required string password
Password
optional string org
Organisation name

list POST GET /list

Main forecast listing and searching endpoint. The output can be PDF or JSON. In the JSON output, the response body for both GET and POST methods looks like this:
[
	{
		"ID" : id,
		"TITLE" : "title",
		"SECTOR_ID" : sector_id,
		"SECTOR_TITLE" : "sector_title",
		"URL" : "http://example.com/page",
	}
]
NOTE ABOUT SECTORS:
The sector can have 'null' as a value in which case there is no sector assigned by Athena. Assuming there is a sector for the forecast, it is possible to get an image from our server as follows:
'http://www.shapingtomorrow.com/images/sectors/' & [SECTOR] & '-' & [Random number between 1 and 5] & '.jpg'
The result should look like this:
'http://www.shapingtomorrow.com/images/sectors/670-3.jpg'

deviceToken and apiKey are required for all requests.

get
Gets a listing of the most recent 1000 Forecasts, optionally by sector and/or tag. You may also submit a 'q' parameter and use this endopint to search the Forecast listing.
Arguments:
optional string q
The search query you wish to submit to the API
optional numeric source
Source ID to display forecasts for
optional numeric sector
Sector ID number to return a list of Forecasts by sector
optional string tag
A tag with which to filter the list, may be used in conjunction with all other arguments, must be URL encoded.
optional boolean ws (default: 0)
If you wish the API to return the WebSummarizer summary of the forecast listing then set this argument to 'true'
required boolean pdf (default: 0)
If you wish the API to return the output as a PDF instead of JSON then set this argument to 'true'
optional numeric year
Include a year parameter to filter results by year.
post
required string q
The search query you wish to submit to the API
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string deviceToken
The deviceToken stored locally after authentication
optional boolean ws (default: false)
If you wish the API to return the WebSummarizer summary of the search results then set this argument to 'true'
optional boolean pdf (default: false)
If you wish the API to return the output as a PDF instead of JSON then set this argument to 'true'

knowledgegraph POST /knowledgegraph

Post a query to the knowledgegraph

post
Submit a query to the knowledge graph
Arguments:
optional string q
The query string
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
optional string nodes
The nodes to look up

contact POST /contact

Contact us, allows the user to send Shaping Tomorrow an email message
deviceToken and apiKey are required for all requests.

post
Post a message and it will be email from the user to Shaping Tomorrow
Arguments:
required string usermessage
The message to be sent
required string msgsubject
The subject of the message
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key
required string deviceToken
The deviceToken stored locally after authentication

challenges GET /challenges

The challenges endpoint serves up challenges to the user based on their client status. The returned JSON object for challenges looks like this:
[
   {
      "TITLE" : "title",
      "ID" : id,
   }
]

The returned JSON object for challenge items looks like this:
[
   {
      "TITLE" : "title",
      "URL" : "http://example.com/page",
   }
]

deviceToken and apiKey are required for all requests.

get
Gets the challenges.
Arguments:
optional numeric challengeid
This argument will cause the endpoint to serve the challenges associated with a particular challenge ID. Without this argument the endpoing will serve up the list of challenges available to the user.

authenticate POST /authenticate

Only the apiKey is required for requests to this endpoint.

post
Your app must submit the ST user's login credentials, the API will return a JSON structure with the DEVICETOKEN for local storage in your app. Subsequent requests to the API must include both apiKey and deviceToken. A 401 HTTP error will be returned if the user's authentication fails.

The JSON response body looks like this:
{
   "DEVICETOKEN": "AB12AB12AB12AB12AB12AB12AB12AB12"
}
Arguments:
required string email
Email address of the ST user
required string password
Password of the ST user
required string deviceId
Device ID of the device accessing the API.
required string apiKey
The API key supplied to the developer by ST, contact api@shapingtomorrow.com for an API key

Resources are listed in matching order. From top to bottom, the first URI to match the request is used.