Developer API

The Hub RESTful API is a free to use, publicly available method of querying the Hub's database of over 100,000 items, including articles, videos, podcasts, events, groups & fundraisers. The result of an API call is presented in JSON format.

In order to use the API, you will be required to register an "app". An app is defined as software or website that will be querying The Hub database. Registration details will include the app name and website. A unique API Key will then be generated for you to use.

To obtain a your API key, send an email to mail@thehub.scot detailing the website address or app name that you intend to use the information on as well as describing what you intend to do with the data. Once approved, a valid API key will be emailed to you.

Each query to the API should be done in POST format, with your API Key posted with the variable "appSecret". Posting without a valid key will result in an error being returned.

The table below shows what can be queried, as well as the Endpoint URI that is used. For clarity, variables in green are included in the Endpoint URI itself, variables in red are POSTed to the Endpoint URI.

Articles
Endpoint URI Variables
https://thehub.scot/api/articles/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

{areaType}
all will load all articles in date order (descending)
popular will load all articles in order of popularity amongst users of The Hub

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

Events
Endpoint URI Variables
https://thehub.scot/api/events/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

mapLat
For querying nearby events, you must include the location's latitude co-ordinate

mapLong
For querying nearby events, you must include the location's longitude co-ordinate

{areaType}
nearby will load all events within a 30 mile radius of given co-ordinates (descending)
upcoming will load all upcoming events in date order (ascending)
archive will load all completed events in date order (descending)

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

Fundraisers
Endpoint URI Variables
https://thehub.scot/api/fundraisers/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

{areaType}
popular will load all fundraisers ordered based on interactions (descending)
new will load all new fundraisers in date order (descending)
ending will load all fundraisers that are ending soon (descending)
complete will load all completed fundraisers in date order (descending)

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

Groups
Endpoint URI Variables
https://thehub.scot/api/group appSecret
This is your API Key and must be included in all queries

group
ID number of group queried. Usually found as the variable "group_id" in other API calls.

https://thehub.scot/api/groups/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

mapLat
For querying nearby groups, you must include the location's latitude co-ordinate

mapLong
For querying nearby groups, you must include the location's longitude co-ordinate

{areaType}
nearby will load groups within 30 mile radius of given co-ordinates
popular will load groups based on membership
new will load groups in order of date created (descending)
parties will load groups marked as being a political party, ordered by membership (descending)

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

Media
Endpoint URI Variables
https://thehub.scot/api/media/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

{areaType}
popular will load all media items in order of popularity (descending)
all will load all media items in order of date created (descending)
livestreams will load livestreams, showing live items first, then upcoming, then archived items
videos will load Youtube, Facebook & Vimeo videos in date order (descending)
podcasts will load podcasts in date order (descending)

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

Member
Endpoint URI Variables
https://thehub.scot/api/member appSecret
This is your API Key and must be included in all queries

memberId or member
Numeric ID of member or alphanumeric userhandle of member (e.g @myName)

Search
Endpoint URI Variables
https://thehub.scot/api/search/{areaType}/{pageNumber} appSecret
This is your API Key and must be included in all queries

{pageNumber}
Numerical value starting at 1. Each page returns 20 results in order of {areaType}

groupId or memberId or searchQuery
Numeric ID of group or member you want to display filtered results for or return results of search query keyword(s)

By using groupId you can filter group content by replacing {areaType} with:

all returns all content for specified group, returned in date order (descending)
articles returns all articles for specified group, returned in date order (descending)
media returns all videos, livestreams & podcasts for specified group, returned in date order (descending)
events returns all events for specified group, returned in order of event start date (descending)
fundraisers returns all fundraisers for specified group, returned in date order (descending)
followers returns all followers for specified group, returned in order of joining (descending).

By using memberId you can filter members content by replacing {areaType} with:

all returns all content for specified member, returned in date order (descending)
shared returns all shared content for specified member, returned in date order (descending)
favourite returns all favourited content for specified member, returned in date order (descending)
events returns all events for specified member, returned in order of event start date (descending)
fundraisers returns all fundraisers for specified member, returned in date order (descending)
groups returns all groups the specified member follows, returned in order of joining (descending)
followers returns all followers for specified member, returned in order of following(descending).
following returns all other members the member is following, returned in order of date followed (descending).

By using searchQuery you can filter content by your search keywords by replacing {areaType} with:

all returns all content based on search keyword(s), returned in date order (descending)
articles returns all articles based on search keyword(s), returned in date order (descending)
posts returns all member posts based on search keyword(s), returned in date order (descending)
media returns all videos, livestreams & podcasts based on search keyword(s), returned in date order (descending)
events returns all eventsbased on search keyword(s), returned in date order (descending)
members returns all members based on search keyword(s)
groups returns all groups based on search keyword(s)
fundraisers returns all fundraisers based on search keyword(s)

Status
Endpoint URI Variables
https://thehub.scot/api/status appSecret
This is your API Key and must be included in all queries

statusId
Numerical status ID of item (usually found named "post_id" in other API query results.

Example API Call
As an example, we will get the very first status posted on The Hub. This example will use PHP and will return a JSON formatted result which can then be parsed to your liking.

<?php
// first set the variables...
$apiKey = "YOURKEYHERE";
$statusId = "1";
$endPointUrl = "https://thehub.scot/api/status";

$data = array('appSecret' => $apiKey, 'statusId' => $statusId);
$options = array(
        'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data),
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($endPointUrl , false, $context);
var_dump($result);
?>

This returns the following result:

string(892) "{{"post_id":"1","post_type":"post_status","post_content":{"content":"The first post on TheHub, a new social media site dedicated to discussing Scottish independence and news\/events surrounding it #StillYes\u00a0"},"share_link":"https:\/\/thehub.scot\/@Murchie\/timeline\/1","share_link_hub":"https:\/\/thehub.scot\/@Murchie\/timeline\/1","post_author":{"user_id":"1","user_name":"Dave","user_handle":"@Murchie","user_verified":"1","user_avatar":"https:\/\/thehub.scot\/uploads\/avatar\/1-1510073368.png"},"post_time":"2015-07-29 23:46:47","post_has_attachment":"0","post_pin_status":"0","post_has_fundraiser":"0","post_interactions":{"post_replies":"0","post_shares":"0","post_likes":"0"},"primary_status":true}]"