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 "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
    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 or the encoded story path. In case you want to lookup by path instead of identifier, set the look_by_path parameter as true and send the path encoded in this field
    look_by_path boolean false In case of true the story will be queried via path instead of identifier
    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
      }
    ]
    

    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

    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/<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 "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
    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
    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.