Introduction

Welcome to the GetSocial API! You can use it to access GetSocial API endpoints, which provide data access to sharing statistics of news articles in public social networks & private messaging apps.

Social API

1. Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: abcdef0123abcdef0123"

Make sure to replace abcdef0123abcdef0123 with your API key.

GetSocial expects that an API key is included in all server requests, in a header as follows:

Authorization: abcdef0123abcdef0123

2. Sites

2.1. Fetch Site

curl "https://analytics.getsocial.io/api/sites?from=2018-01-01&to=2018-01-05" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "visits": 410275,
  "shares": 50749,
  "referrals": 61051,
  "sharing_rate": 12.37
}

This endpoint retrieves analytics data for a site observed between two specific dates (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/sites

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data

Returns

Field	Type	Description
visits	integer	Number of visits to the website
shares	integer	Number of shares performed by users
referrals	integer	Number of visits generated by user's shared posts
sharing_rate	float	Rate of users sharing the website

3. Stories

3.1. Top Stories

curl "https://analytics.getsocial.io/api/stories/top?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "75dfd2a4fb79",
    "visits": 123,
    "shares": 40,
    "referrals": 150,
    "sharing_rate": 35.52,
    "viral_score": 75.23,
    "recirculation_percentage": 3.4,
    "recirculation_depth": 2.43,
    "title": "The Precipice",
    "path": "/"
  },
  {
    "identifier": "f15a173dd497",
    "visits": 190,
    "shares": 51,
    "referrals": 40,
    "sharing_rate": 26.84,
    "viral_score": 5.23,
    "recirculation_percentage": 4.3,
    "recirculation_depth": 4.21,
    "title": "The Frigate Pallada",
    "path": "/",
    "cursor_id": "f15a173dd497_51"
  }
]

This endpoint retrieves the overall top stories, with total visits, shares, referrals, share rate, virality score and recirculation between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/stories/top

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort stories, can be visits, shares, referrals, sharing_rate, viral_score, recirculation_percentage or recirculation_depth
limit	number	10	Max number of results to retrieve. The maximum allowed is 500
starting_after	string	-	A cursor for use in pagination, an object ID that defines the place in the list. For instance, if you make a list request and receive 10 objects, ending with cursor_id=f15a173dd497_51, your subsequent call can include starting_after=f15a173dd497_51 in order to fetch the next page of the list. The cursor_id value is available in the last returned story

Returns

Field	Type	Description
-	Story[]	Top stories

3.2. Top Stories in last 24-hours

curl "https://analytics.getsocial.io/api/stories/top?limit=3&sort_by=referrals" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "75dfd2a4fb79",
    "path": "/lyfestyle/article-z",
    "title": "Article z",
    "visits": 100,
    "shares": 40,
    "sharing_rate": 40.0,
    "viral_score": 30.04,
    "recirculation_percentage": 3.4,
    "recirculation_depth": 2.42,
    "referrals": 150
  },
  {
    "identifier": "f15a173dd497",
    "path": "/sport/article-x",
    "title": "Article x",
    "visits": 60,
    "shares": 51,
    "sharing_rate": 85.0,
    "viral_score": 10.32,
    "recirculation_percentage": 4.3,
    "recirculation_depth": 4.29,
    "referrals": 40
  },
  {
    "identifier": "5f341a5d899a",
    "path": "/sport/article-y",
    "title": "Article y",
    "visits": 150,
    "shares": 100,
    "sharing_rate": 66.67,
    "viral_score": 2.19,
    "recirculation_percentage": 5.4,
    "recirculation_depth": 1.03,
    "referrals": 122
  }
]

This endpoint retrieves the top stories in the last 24 hours sorted by a specific metric. It can be used to retrieve the most shared, most referred, most visited, most viral stories or most recirculated stories.

HTTP Request

GET https://analytics.getsocial.io/api/stories/top

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Number of stories to be retrieved
sort_by	string	shares	Criteria by which to sort stories, can be visits, shares, referrals, sharing_rate, viral_score, recirculation_percentage or recirculation_depth

Returns

Field	Type	Description
-	Story[]	Top stories

3.3. Fetch Story

curl "https://analytics.getsocial.io/api/stories/abcd1234?from=2018-01-01&to=2018-01-31&with_channels=true" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "identifier": "abcd1234",
  "title": "De Petersburgse pest",
  "path": "/",
  "visits": 213,
  "shares": 40,
  "referrals": 150,
  "viral_score": 27.85,
  "sharing_rate": 6.25,
  "recirculation_percentage": 12.3,
  "recirculation_depth": 4.32,
  "channels": {
    "DarkSocial": {"shares": 10, "referrals": 120, "viral_score": 3.05, "recirculation_percentage": 1.2, "recirculation_depth": 4},
    "Facebook": {"shares": 30, "referrals": 30, "viral_score": 5.05, "recirculation_percentage": 2.2, "recirculation_depth": 4},
  }
}

This endpoint retrieves the story information with total visits, shares, referrals, share rate and virality score between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/stories/<story_id>

Query Parameters

Parameter	Type	Default	Description
story_id	string	-	Story identifier. In case you want to lookup by path instead of identifier, set the query parameter with the path encoded. In that case, set story_id as id
query	string	-	The parameter is optional but in case of present the story will be queried via the value given by this parameter instead of the value given by story_id
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
with_channels	boolean	false	In case of true the analytics data for each channel is also provided

Returns

Field	Type	Description
identifier	string	The story identifier
visits	integer	Number of visits to the story
shares	integer	Number of shares performed on the story
referrals	integer	Number of visits generated by user's shared posts relative to this story
sharing_rate	float	Rate of users sharing the story
recirculation_percentage	float	Percentage of recirculations from referrals
recirculation_depth	float	Average depth of recirculations from referrals
viral_score	float	Organic virality index of the story
title	string	The story title
path	string	The story URL path

3.4. Fetch Story Identifier

curl "https://analytics.getsocial.io/api/stories/resolve_id/?path=/article-104" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "identifier": "efgh5678"
}

This endpoint retrieves the story identifier that identifies a story, given it's path.

The path must be clean of query arguments and hashtags, and should be CGI/HTML form encoded, although an attempt is made to understand misencoded paths. For example for the URL http://example.com/path/site.htm?arg=1#top the path should be %2Fpath%2Fsite.htm.

HTTP Request

GET https://analytics.getsocial.io/api/stories/resolve_id

Query Parameters

Parameter	Type	Default	Description
path	string	-	Story path

Returns

Field	Type	Description
identifier	string	The story identifier

3.5. Top Story Users

curl "https://analytics.getsocial.io/api/stories/abcd1234/users?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "friend@gmail.com",
    "visits": 113,
    "shares": 21,
    "referrals": 64
  },
  {
    "identifier": "enemy@gmail.com",
    "visits": 81,
    "shares": 18,
    "referrals": 72
  }
]

This endpoint retrieves the top users for the story, with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/stories/<story_id>/users

Query Parameters

Parameter	Type	Default	Description
story_id	string	-	Story identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort top users, can be visits, shares or referrals
limit	number	10	Max number of results to retrieve

Returns

Field	Type	Description
identifier	string	The user identifier
visits	integer	Number of visits to the story by the user
shares	integer	Number of shares performed on the story by the user
referrals	integer	Number of visits generated by the user's shared posts relative to this story
title	string	The story title
path	string	The story URL path

3.6. Top recirculation destinations

On GetSocial, we measure recirculation of articles that were visited from a share. This endpoint retrieves the most recirculated to stories (destination stories).

If you instead need the top stories or channels by own recirculation please see endpoints 3.1. Top Stories and 5.1. Top Channels, with a sort criteria of recirculation.

curl "https://analytics.getsocial.io/api/stories/top/recirculated_to?limit=2&from=2018-01-01&to=2018-01-31" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "path": "/",
    "identifier": "abcd1234",
    "title": "Lifestyle Global",
    "count": 301980
  },
  {
    "path": "/7-dieting-tips",
    "identifier": "aceg1357",
    "title": "Our top 7 dieting tips",
    "count": 32134
  }
]

HTTP Request

GET https://analytics.getsocial.io/api/stories/top/recirculated_to

Query Parameters

Parameter	Type	Default	Description
story_id	string	-	Source Story ID; is optional
channel	string	-	Source Channel ID, like facebook or twitter; is optional
from	string	-	Date from which to start counting data; is required
to	string	-	Date to which to stop counting data; is required
limit	number	10	Max number of results to retrieve; 100 is the hard limit by request

Returns

List of top recirculated to stories, with times visited.

3.7. Top Story Locations

curl "https://analytics.getsocial.io/api/stories/abcd1234/locations?from=2018-01-01&to=2018-01-31&sort_by=shares" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "country_code": "PT",
    "region": "Lisboa",
    "shares": 3500,
    "referrals": 1500
  },
  {
    "country_code": "PT",
    "region": "Porto",
    "shares": 3000,
    "referrals": 2345
  },
  {
    "country_code": "ES",
    "region": "Madrid",
    "shares": 2670,
    "referrals": 1500
  }
]

This endpoint retrieves the top locations for the story, with total shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/stories/<story_id>/locations

Query Parameters

Parameter	Type	Default	Description
story_id	string	-	Story identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data

Fields in array response

Field	Type	Description
country_code	string	The country code on ISO 3166-1 alpha-2 format
region	string	The region name
shares	integer	Number of shares performed on that region
referrals	integer	Number of visits on that region generated by shared posts

4. Users

All user-related endpoints only consider actions by known users: you must make use of our influencers feature.

4.1. Top Users

curl "https://analytics.getsocial.io/api/users/top?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "friend@gmail.com",
    "visits": 5,
    "shares": 40,
    "referrals": 150
  },
  {
    "identifier": "enemy@gmail.com",
    "visits": 31,
    "shares": 9,
    "referrals": 12,
    "cursor_id": "12345_9"
  }
]

This endpoint retrieves the overall top users, with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/users/top

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort users, can be visits, shares or referrals
limit	number	10	Max number of results to retrieve. The maximum allowed is 500
starting_after	string	-	A cursor for use in pagination, an object ID that defines the place in the list. For instance, if you make a list request and receive 10 objects, ending with cursor_id=f15a173dd497_51, your subsequent call can include starting_after=f15a173dd497_51 in order to fetch the next page of the list. The cursor_id value is available in the last returned user

Returns

Field	Type	Description
-	User[]	Top users

4.2. Fetch User

curl "https://analytics.getsocial.io/api/users/friend%40gmail.com?from=2018-01-01&to=2018-01-31" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "identifier": "friend@gmail.com",
  "visits": 213,
  "shares": 40,
  "referrals": 150
}

This endpoint retrieves the user information with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/users/<user_id>

Query Parameters

Parameter	Type	Default	Description
user_id	string	-	User identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data

Returns

Field	Type	Description
identifier	string	User identifier
visits	integer	Number of visits performed by the user
shares	integer	Number of shares performed by the user
referrals	integer	Number of visits generated by the user's shared posts

4.3. Top User Stories

curl "https://analytics.getsocial.io/api/users/friend%40gmail.com/stories?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "abcd1234",
    "visits": 5,
    "shares": 40,
    "referrals": 150,
    "title": "First Love",
    "path": "/first-love/40100ff-0"
  },
  {
    "identifier": "abcd1235",
    "visits": 31,
    "shares": 9,
    "referrals": 12,
    "title": "Home of the Gentry",
    "path": "/index.htm"
  }
]

This endpoint retrieves the top stories for the user, with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/users/<user_id>/stories

Query Parameters

Parameter	Type	Default	Description
user_id	string	-	User identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort stories, can be visits, shares or referrals
limit	number	10	Max number of results to retrieve

Returns

Field	Type	Description
identifier	string	Story identifier
visits	integer	Number of visits performed by the given user to the story
shares	integer	Number of shares performed by the given user to the story
referrals	integer	Number of visits generated by the given user's shared posts on the story
title	integer	Story title
path	integer	Story path

4.4. Top User Channels

curl "https://analytics.getsocial.io/api/users/friend%40gmail.com/channels?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "darksocial",
    "visits": 81,
    "shares": 40,
    "referrals": 150
  },
  {
    "identifier": "twitter",
    "visits": 12,
    "shares": 9,
    "referrals": 12
  }
]

This endpoint retrieves the top channels for the user, with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/users/<user_id>/channels

Query Parameters

Parameter	Type	Default	Description
user_id	string	-	User identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort channels, can be visits, shares or referrals
limit	number	10	Max number of results to retrieve

Returns

Field	Type	Description
identifier	string	Channel identifier
visits	integer	Number of visits performed by the given user via channel
shares	integer	Number of shares performed by the given user via channel
referrals	integer	Number of visits generated by the given user's shared posts on the channel

5. Channels

5.1. Top Channels

curl "https://analytics.getsocial.io/api/channels/top?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "Facebook",
    "shares": 40,
    "referrals": 150,
    "viral_score": 100.0,
    "recirculation_percentage": 0.05,
    "recirculation_depth": 1.3
  },
  {
    "identifier": "Twitter",
    "shares": 9,
    "referrals": 12,
    "viral_score": 12.0,
    "recirculation_percentage": 0.12,
    "recirculation_depth": 1.5
  }
]

This endpoint retrieves the overall top channels, with total shares and referrals, viral score and recirculation between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/channels/top

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Metric used to sort channels. Accepted values are shares, referrals, viral_score, recirculation_percentage and recirculation_depth
limit	number	10	Max number of results to retrieve

Returns

An array of channels where each one is represented by:

Field	Type	Description
identifier	string	The channel identifier
shares	integer	Number of shares performed on the website via channel
referrals	integer	Number of visits generated by shared posts of the website via channel
viral_score	float	Virality score of channel
recirculation_percentage	float	Average recirculation from referrals
recirculation_depth	float	Average depth of sessions that started from a referral

5.2. Top Channels in last 24-hours

curl "https://analytics.getsocial.io/api/channels/top?limit=3&sort_by=referrals" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "Facebook",
    "shares": 40,
    "referrals": 150,
    "viral_score": 100.0,
    "recirculation_percentage": 0.15,
    "recirculation_depth": 1.12
  },
  {
    "identifier": "Twitter",
    "shares": 10,
    "referrals": 80,
    "viral_score": 60.0,
    "recirculation_percentage": 0.23,
    "recirculation_depth": 3.5
  },
  {
    "identifier": "DarkSocial",
    "shares": 10,
    "referrals": 30,
    "viral_score": 20.0,
    "recirculation_percentage": 1.34,
    "recirculation_depth": 4.12
  }
]

This endpoint retrieves the top channels in the last 24 hours sorted by a specific metric. It can be used to retrieve the most shared and most referred channels.

HTTP Request

GET https://analytics.getsocial.io/api/channels/top

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Number of channels to be retrieved
sort_by	string	shares	Metric used to sort channels. Accepted values are shares, referrals, viral_score, recirculation_percentage and recirculation_depth

Returns

An array of channels where each one is represented by:

Field	Type	Description
identifier	string	The channel identifier
shares	integer	Number of shares performed on the website via channel
referrals	integer	Number of visits generated by shared posts of the website via channel
viral_score	float	Virality score of channel
recirculation_percentage	float	Average recirculation from referrals
recirculation_depth	float	Average depth of sessions that started from a referral

5.3. Top Channel Users

curl "https://analytics.getsocial.io/api/channels/facebook/users?from=2018-01-01&to=2018-01-31&sort_by=shares&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "identifier": "friend@gmail.com",
    "visits": 113,
    "shares": 21,
    "referrals": 64
  },
  {
    "identifier": "enemy@gmail.com",
    "visits": 81,
    "shares": 18,
    "referrals": 72
  }
]

This endpoint retrieves the top users for the channel, with total visits, shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/channels/<channel_id>/users

Query Parameters

Parameter	Type	Default	Description
channel_id	string	-	Channel identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort users, can be visits, shares or referrals
limit	number	10	Max number of results to retrieve

Returns

An array of users where each one is represented by:

Field	Type	Description
identifier	string	The user identifier
shares	integer	Number of shares performed on the website by the user via a given channel
referrals	integer	Number of visits generated by shared posts of the website by the user via a given channel

5.4. Top Channel Locations

curl "https://analytics.getsocial.io/api/stories/abcd1234/locations?from=2018-01-01&to=2018-01-31&sort_by=shares" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "country_code": "PT",
    "region": "Lisboa",
    "shares": 3500,
    "referrals": 1500
  },
  {
    "country_code": "PT",
    "region": "Porto",
    "shares": 3000,
    "referrals": 2345
  },
  {
    "country_code": "ES",
    "region": "Madrid",
    "shares": 2670,
    "referrals": 1500
  }
]

This endpoint retrieves the top locations for the story, with total shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/channels/<channel_id>/locations

Query Parameters

Parameter	Type	Default	Description
channel_id	string	-	Channel identifier
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data

Fields in array response

Field	Type	Description
country_code	string	The country code on ISO 3166-1 alpha-2 format
region	string	The region name
shares	integer	Number of shares performed on that region
referrals	integer	Number of visits on that region generated by shared posts

6. Events

To start using events, first create event types in your GetSocial dashboard.

6.1. List Events

curl "https://analytics.getsocial.io/api/events/list?from=2018-01-01&to=2018-01-31&user=1200139&channel=facebook&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "user": "1200139",
    "date": "2018-07-02 15:38:15 +0100",
    "story": "story-id-13411",
    "channel": "facebook",
    "type": "a1b2c3",
    "attributes": {
      "total": "USD 1198.05"
    }
  },
  {
    "user": "1200139",
    "date": "2018-07-02 15:38:05 +0100",
    "story": "story-id-22001",
    "channel": "facebook",
    "type": "d4e5f6",
    "attributes": null
  }
]

This endpoint retrieves a complete list of individual conversion events, with the attributes provided on submission.

HTTP Request

GET https://analytics.getsocial.io/api/events/list

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data; is required
to	string	-	Date to which to stop counting data; is required
user	string	-	Argument with which to refine search, must be matched if present
story	string	-	Argument with which to refine search, must be matched if present
channel	string	-	Argument with which to refine search, must be matched if present
type	string	-	Argument with which to refine search, must be matched if present
limit	number	10	Max number of results to retrieve; 1000 is the hard limit by request

Returns

List of detailed conversion events, ordered by date.

6.2. Count Events

curl "https://analytics.getsocial.io/api/events/count?story=274819848&type=purchases" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "count": 122
}

This endpoint counts the total number of events given the query arguments provided.

HTTP Request

GET https://analytics.getsocial.io/api/events/count

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data; is required
to	string	-	Date to which to stop counting data; is required
user	string	-	Argument with which to refine search, must be matched if present
story	string	-	Argument with which to refine search, must be matched if present
channel	string	-	Argument with which to refine search, must be matched if present
type	string	-	Argument with which to refine search, must be matched if present

Returns

Total number of elements found.

6.3. Count Events By Attribute

curl "https://analytics.getsocial.io/api/events/count/channels?from=2018-01-01&to=2018-01-31&user=AmAm1234&limit=2" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "id": "facebook",
    "count": 31
  },
  {
    "id": "twitter",
    "count": 13
  }
]

Counts number of results grouped by an attribute (channel in this example), optionally filtered by user, story channel or event type.

HTTP Request

GET https://analytics.getsocial.io/api/count/<attribute>

Query Parameters

Parameter	Type	Default	Description
attribute	string	-	Attribute with which to group event counts (users, stories, channels or types); is required
from	string	-	Date from which to start counting data; is required
to	string	-	Date to which to stop counting data; is required
user	string	-	Argument with which to refine search, must be matched if present
story	string	-	Argument with which to refine search, must be matched if present
channel	string	-	Argument with which to refine search, must be matched if present
type	string	-	Argument with which to refine search, must be matched if present
limit	number	10	Max number of results to retrieve; 1000 is the hard limit by request

Returns

List of events grouped by an attribute, with the corresponding ID per element; sorted by number of results.

7. Locations

7.1. Top Locations

curl "https://analytics.getsocial.io/api/locations/top?from=2018-01-01&to=2018-01-31&sort_by=shares" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

[
  {
    "country_code": "PT",
    "region": "Lisboa",
    "shares": 3500,
    "referrals": 1500
  },
  {
    "country_code": "PT",
    "region": "Porto",
    "shares": 3000,
    "referrals": 2345
  },
  {
    "country_code": "ES",
    "region": "Madrid",
    "shares": 2670,
    "referrals": 1500
  },
  {
    "country_code": "US",
    "region": "Oregon",
    "shares": 2500,
    "referrals": 1240
  }
]

This endpoint retrieves the overall top locations, with total shares and referrals between the two dates specified (inclusive).

HTTP Request

GET https://analytics.getsocial.io/api/locations/top

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start counting data
to	string	-	Date to which to stop counting data
sort_by	string	shares	Criteria by which to sort locations, can be shares or referrals

Fields in array response

Field	Type	Description
country_code	string	The country code on ISO 3166-1 alpha-2 format
region	string	The region name
shares	integer	Number of shares performed on that region
referrals	integer	Number of visits on that region generated by shared posts

8. Short Links

8.1. Create Short Link

curl -X POST "https://analytics.getsocial.io/api/links" \
  -H "Authorization: abcdef0123abcdef0123"
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "url=http://example.com/path"

The above command returns a JSON structured like this:

{
  "result": "ok",
  "link": "https://api.at.getsocial.io/abcdef",
  "id": "123456"
}

This endpoint creates a new short link, given a URL belonging to your website. You can later find it also on your GetSocial dashboard.

HTTP Request

POST https://analytics.getsocial.io/api/links

Query Parameters

Parameter	Type	Default	Description
url	string	-	URL to shorten; must include website domain and protocol

Response fields

Field	Type	Description
result	string	Whether call was successful. Is ok or err, in case of error
id	string	The short link ID
link	string	The short link created

8.2. Fetch Link Statistics

curl "https://analytics.getsocial.io/api/links/abcdef?from=2020-01-20" \
  -H "Authorization: abcdef0123abcdef0123"

The above command returns a JSON structured like this:

{
  "sequence": {
    "referrals": [],
    "earned": [],
    "total_traffic": []
  },
  "totals": {
    "referrals": 0,
    "earned": 0,
    "total_traffic": 0,
    "shares": 0,
    "uplift": 0
  },
  "channels":{
    "Dark Social": {
      "referrals": 0,
      "shares": 0,
      "earned": 0,
      "total_traffic": 0,
      "viral_uplift": 0
    }
  }
}

This endpoint retrieves all data, optionally since the date specified (subject to the website timezone). If the date is the current date, the sequence field shows hourly data, otherwise it shows daily data.

The short link ID is required. You can find it in the response from the previous endpoint, or in your GetSocial dashboard. For instance at https://getsocial.io/sites/your-website-com/link-detail/LINK_ID.

HTTP Request

GET https://analytics.getsocial.io/api/api/<link_id>

Query Parameters

Parameter	Type	Default	Description
from	string	-	Date from which to start retrieving data, in 2020-08-20 format

Response fields

Field	Type	Description
sequence	hash	Referrals, earned visits and total traffic, discriminated by day or hour
totals	hash	Total statistics for the time period
channels	hash	Statistics by channel for the time period

Errors

The GetSocial API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Malformed request syntax.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- Endpoint or object identifier not found.
406	Not Acceptable -- You requested a format that isn't JSON.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.