NAV Navbar
shell
  • Introduction
  • Social API
  • Errors
  • 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 "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 http://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 "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": "/"
      }
    ]
    

    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 http://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

    Returns

    Field Type Description
    - Story[] Top stories

    3.2. Top Stories in last 24-hours

    curl "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 http://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 "analytics.getsocial.io/api/stories/abcd1234?from=2018-01-01&to=2018-01-311" \
      -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
    }
    

    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 http://analytics.getsocial.io/api/stories/<story_id>

    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

    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 "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 http://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 "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 http://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 "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 http://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 "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 http://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

    Returns [] where each element is defined by

    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 "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
      }
    ]
    

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

    HTTP Request

    GET http://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

    Returns

    Field Type Description
    - User[] Top users

    4.2. Fetch User

    curl "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 http://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 "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 http://analytics.getsocial.io/api/users/<channel_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 "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": "facebook",
        "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 http://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

    4.5. Fetch User Flow

    curl "analytics.getsocial.io/api/users/friend%40gmail.com/flow" \
      -H "Authorization: abcdef0123abcdef0123"
    

    The above command returns a JSON structured like this:

    {
      "visits": 213,
      "shares": 10,
      "referrals": 150,
      "conversions": 3,
      "origin_channel": "Twitter",
      "shares_by_channel": {
        "Facebook": 4,
        "DarkSocial": 6
      }
      "referrals_by_channel": {
        "Facebook": 100,
        "DarkSocial": 50
      },
      "conversions_by_channel": {
        "Facebook": 3
      },
      "conversions_by_story": {
        "/": 1,
        "/article-xyz": 2
      }
    }
    

    This endpoint retrieves the total user data recorded since their first session.

    HTTP Request

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

    Returns

    Parameter Type Description
    visits number Number of user sessions
    shares number Number of shares performed by the current user, via share bar or copying & pasting the URL
    referrals number Number of sessions generated by the current user shared posts
    conversions number Number of conversions generated by the current user shared posts
    origin_channel string Last known origin of the current user
    shares_by_channel Hash Number of shares performed by the current user, discriminated by channel
    referrals_by_channel Hash Number of sessions generated by the current user, discriminated by channel
    conversions_by_channel Hash Number of conversions generated by the current user, discriminated by channel
    conversions_by_story Hash Number of conversions generated by the current user, discriminated by URL path

    5. Channels

    5.1. Top Channels

    curl "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 http://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 "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": "CopyPaste",
        "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 http://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 "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 http://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 "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 http://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

    Returns [] where each element is defined by

    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 "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 http://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 "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 http://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 "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 http://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 "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 http://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

    Returns [] where each element is defined by

    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

    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.