Where Google Analytics ends, Social Report is just beginning...

Social Report API

Overview

The Social Report SDKs gets your app connected quickly and easily, so you can focus on creating an experience. Social Report exposes its data via an Application Programming Interface (API), so developers can interact in a programmatic way with the Social Report website. This document is the official reference for that functionality.

The purpose of this API is to allow anyone to build applications that interact with social networks using a unified API without having to worry about integrating with each network separately.

Version

The current API version is 1.0

Authentication

All requests have to be signed using an api key that. Simply add "api_key" request header when making all requests. For testing purposes you can also pass "api_key" as a parameter. This is not a recommended option however for obvious security reasons.

Obtain API Key

If you have an existing Social Report account you can find your API in My Account > API Access section. If you don't have an account - you can create it here.

https://api.socialreport.com/projects.svc

Get a list of all projects belonging to the owner of the API key.

Parameters

  • user: user identifier (optional)

Output

  • id: unique project identifier.
  • name: project name.
  • user: user identifier (optional)
[
    {
        "id": "56783",
        "name": "SocialReport.com",
        "user": 5
    },
    {
        "id": "76897",
        "name": "WebAlgorithm LLC"
    },
    {
        "id": "45765",
        "name": "ConcreteMedia Inc",
        "user": 7
    }

]
                            

https://api.socialreport.com/projectCreate.svc

Create a new project. Project is a way of grouping a set of social properties. Typically project represents a client, a business or a marketing initiative.

Parameters

  • name: project name
  • user: project owner user identifier (optional).

Output

  • id: unique project identifier.
[
    {
        "id": "56783"
    }

]
                            

https://api.socialreport.com/projectSummary.svc

Get a project summary for a project - analytical summary of social trends

Parameters

  • project: project identifier

Output

 {
    "project": 56783,
    "name": "SocialReport.com",
    "summary": {
        "date": "20120502",
        "accounts": 25,
        "networks": 19,
        "friends": 2107,
        "mostPopulaNetwork": "LinkedIn",
        "mostPopulaNetworkShare": 0.0002,
        "mostPopularLanguages": "English,Spanish,Italian",
        "membershipGrowth": 0.00128,
        "activityGrowth": -0.00729,
        "activeCountries": "United States,Italy,India",
        "engagement": 0.601,
        "engagementGrowth": 0.001,
        "dailyClicks": 0.011,
        "averageAge": 35,
        "countries": 47,
        "numberOfLanguages": 37,
        "mostActiveCities": "New York,Brooklyn,Jersey City",
        "mostActiveStates": "Connecticut,Illinois"
    }
}
       

https://api.socialreport.com/projectAddUser.svc

Add user to the project. Each user gets a very specific set of permissions.

Parameters

  • project: project identifier
  • email: user email address
  • firstName: user's first name (only required for first time user setup)
  • lastName: user's last name (only required for first time user setup)
  • company: user's company (only required for first time user setup)
  • username: user's username (only required for first time user setup)
  • password: user's password (only required for first time user setup)
  • active: can user get access to project (optional) yes - user can access to project (default), no - user can't access to project
  • accounts: can user get access to accounts. Available values - yes or no
  • addAccount: can user add new account to project. Available values - yes or no
  • agents: can user get access to keyword agents. Available values - yes or no
  • campaigns: can user get access to campaigns. Available values - yes or no
  • contacts: can user get access to address book. Available values - yes or no
  • export: can user get access to data export. Available values - yes or no
  • goals: can user get access to goals. Available values - yes or no
  • reports: can user get access to reports. Available values - yes or no
  • api: can user execute api requests. Available values - yes or no
  • notifications: can user get notifications. Available values - yes or no

Output

  • id: unique user identifier.
[
    {
        "id": "6543"
    }

]
                            

https://api.socialreport.com/projectModifyUser.svc

Make changes to your project users - their profile data and permissions.

Parameters

  • project: project identifier
  • user: user identifier
  • active: can user get access to project (optional) yes - user can access to project (default), no - user can't access to project
  • accounts: can user get access to accounts. Available values - yes or no
  • addAccount: can user add new account to project. Available values - yes or no
  • agents: can user get access to keyword agents. Available values - yes or no
  • campaigns: can user get access to campaigns. Available values - yes or no
  • contacts: can user get access to address book. Available values - yes or no
  • export: can user get access to data export. Available values - yes or no
  • goals: can user get access to goals. Available values - yes or no
  • reports: can user get access to reports. Available values - yes or no
  • api: can user execute api requests. Available values - yes or no
  • notifications: can user get notifications. Available values - yes or no

Output

  • id: unique user identifier.
[
    {
        "id": "6543"
    }

]
                            

https://api.socialreport.com/projectRemoveUser.svc

Remove user from the project. This strips the user from all access to specified project. This does not deactivate the user.

Parameters

  • project: project identifier
  • user: user identifier.

Output

[
    {
        "status": "ok"
    }
]
                            

https://api.socialreport.com/projectUsers.svc

Get a list of users who have access to specified project.

Parameters

  • project: project identifier

Output

[
    {
        "id": "11833",
        "lastName": "johnson",
        "added": "20111031",
        "email": "user1@company.com",
        "active": "yes",
        "firstName": "roger",
        "deleted": "no"
    },
    {
        "id": "11317",
        "lastName": "robinson",
        "added": "20111031",
        "created": "20100901",
        "email": "user2@company.com",
        "active": "no",
        "firstName": "peter",
        "deleted": "no"
    }
]
                            

https://api.socialreport.com/accounts.svc

Get a list of all accounts for a specified project. Accounts are the actual social properties: twitter profiles, facebook pages, etc.

Parameters

  • project: project identifier

Output

  • id: unique account identifier.
  • name: account name.
  • type: account network type (i.e. T (Twitter), F (Facebook), etc) .
  • active: activity indicator.
[
    {
        "id": "65789",
        "name": "web@lgorithm",
        "active": "yes",
        "type": "T"
    },
    {
        "id": "45678",
        "name": "SocialReport.com",
        "active": "yes",
        "type": "F"
    },
    {
        "id": "62821",
        "name": "@TheSocialReport",
        "active": "yes",
        "type": "F"
    },
    {
        "id": "87601",
        "name": "socialreport",
        "active": "yes",
        "type": "BITLY"
    },
    {
        "id": "248",
        "name": "Dunkin Donuts",
        "active": "yes",
        "type": "YELP"
    }
]
                            

https://api.socialreport.com/publications.svc

Get a list of all campaigns for a project. Campaigns are publications into mutliple social channels with ability to track clicks and conversions.

Parameters

  • project: project identifier

Output

  • id: unique campaign identifier.
  • name: campaign name.
  • type: campaign type (i.e. L - manual, RSS - rss syndication)
  • status: current campaign status.
[
    {
        "id": "1061",
        "status": "pending",
        "name": "sr blog",
        "type": "RSS",
        "approved": "yes"
    },
    {
        "id": "1059",
        "status": "inprogress",
        "name": "monday 9:37",
        "type": "L",
        "approved": "yes"
    }
]
                            

https://api.socialreport.com/publicationDetail.svc

Retrieve complete performance report of a particular publication

Parameters

  • id: publication identifier

Output

{
    "id": 1326,
    "project": 111117,
    "name": "Your publication title",
    "status": "published",
    "created_utc": 1358513008000,
    "approved": "yes"
    "schedule": {
        "20140118 15:43 +0300": {
            "id": 1397,
            "date_utc": 1358513008000,
            "message": "Your publication message will go here"
        }
    },
    "accounts": [
        277,
        259,
        273
    ],
    "publications": [
        {
            "account": 273,
            "date_utc": 1367478322000,
            "schedule_id": 1397,
            "post_id": "iEgcb1QP9L1EmB_9pKq5fuXO1OCJ53dCZR9Sjeko9Cc"
        },
        {
            "account": 277,
            "date_utc": 1367478315000,
            "schedule_id": 1397,
            "post_id": "371193063000486",
            "post_url": "http://www.facebook.com/permali..."
        },
        {
            "account": 259,
            "date_utc": 1367478309000,
            "schedule_id": 1397,
            "post_id": "UNIU-149754396-5735619739678437376-SHARE",
            "post_url": "http://www.linkedin.com/update...."
        },
        {
            "account": 259,
            "date_utc": 1367477876000,
            "schedule_id": 1397
        },
        {
            "account": 10031,
            "date_utc": 1367477876000,
            "schedule_id": 1397,
            "post_id": "389746597783209",
            "post_url": "http://www.facebook.com/302294..."
        }

    ],
    "result": {
        "clicks": 11,
        "conversions": 4
    }
}
                            

https://api.socialreport.com/publications.svc

Register new customers. Note that this API must be used over SSL and only accepts "POST" request.

Create a new publication. This method only accepts "POST" requests.

Request Body

  • project: project identifier
  • name: publication name required but only used to publish to Blogger, LinkedIn Groups and WordPress
  • accounts: JSON array of accounts (i.e. [10031,275])
  • schedule: JSON array of schedule objects see below example
  • image: if you are including an image, specify its url here
  • roi: return on investment configuration, see below example
  • targeting: specialized publication targeting, see below example
{
    "project": 1,
    "name": "My First Publication",
    "accounts": [
        10031,
        275
    ],
    "schedule": {
        "20141012 12:12 EST": {
            "message": "message 1 text http://www.socialreport.com",
            "twitterMessage": "twitter message 1 #smm"
        },
        "20141015 12:12 EST": {
            "message": "message 2 text http://www.socialreport.com",
            "twitterMessage": "twitter message 2 #smm"
        }
    },
    "image": "http://www.socialreport.com/includes/logo.png",
    "roi": {
        "campaignCost": 15,
        "conversionValue": 10,
        "conversionCost": 1
    },
    "call_action": {
        "type": "LEARN_MORE",
        "title": "Sample Call To Action Title"
    },
    "targeting": {
        "geo": {
            "longitude": 90,
            "latitude": 80
        },
        "countries": [
            "ES",
            "US"
        ],
        "age": {
            "from": 14,
            "to": 35
        },
        "gender": [
            "male",
            "female"
        ],
        "relationshipStatus": [
            "married",
            "single"
        ]
    }
}
        

Output

Returns publication identifier
[{"id":"5567532"}]
                            

https://api.socialreport.com/export.svc

Exports all account data. Note that the result is a downloadable zip archive file.

Parameters

  • export_type: support types: account, campaign, agent, conversation, address-book
  • account: account (required if export_type=account)
  • campaign: account (required if export_type=campaign)
  • project: account (required if export_type=address-book)
  • project: account (required if export_type=address-book or conversation)
  • accounts: account (required if export_type=conversation)
  • from: from date offset (i.e. 20110925)
  • to: to date offset (i.e. 20111025). note that maximum allowed date range is 30 days.

Additional parameters. Value 1 indicates the need to export data

  • activity: export activity.
  • countries: export geo by countries.
  • cities: export geo by cities.
  • interests: export interests.
  • followers: export followers. Twitter only
  • following: export following. Twitter only
  • twitter_list: export lists. Twitter only
  • twitter_reference: export references. Twitter only
  • twitter_messages: export twitter messages. Twitter only
  • twitter_klout: export klout results. Twitter only
  • friends: export friends. Facebook, Meetup, Linkedin, MySpace, Vimeo, Yelp, YouTube only
  • job_titles: export jobs titles. Facebook, Linkedin only
  • school: export schools. Facebook, Linkedin only
  • posts: export posts. Facebook only
  • foursquare_checkins: export checkins. Foursquare only
  • foursquare_tips: export tips. Foursquare only
  • foursquare_users: export users. Foursquare only
  • linkedin_jobs: export jobs. Linkedin only
  • subscribers: export subscribers. YouTube only
  • video: export videos. YouTube only
  • video_activity: export activity by video. YouTube only
  • video_demographic: export demographic by video. YouTube only
  • video_geo: export geo by video. YouTube only
  • video_referrers: export referrers by video. YouTube only
  • hostname: export hostnames. GoogleAnalytics only
  • keyword_activity: export activity by keywords. GoogleAnalytics only
  • geo: export geo. GoogleAnalytics, Bitly only
  • link_activity: export activity by links. Bitly only
  • geo_activity: export activity by geo. Bitly only
  • referral_activity: export activity by referrerak. Bitly only
  • browsers: export data by browsers. Goo.ly only
  • clicks: export data by clicks. Goo.ly only
  • referrals: export referrals. Goo.ly only
  • links: export data by links. Goo.ly only
  • post_activity: export activity by posts. WordPress only
  • comment_activity: export activity by comments. WordPress only
  • search_term_activity: export activity by search terms. WordPress only
  • users: export users. WordPress only
  • orders: export orders. Shopify only
  • products: export products. Shopify only
  • customers: export customers. Shopify only
  • ebay_items: export items. Ebay only
  • ebay_orders: export orders. Ebay only
  • ebay_users: export users. Ebay only
  • etsy_listings: export listings. Etsy only
  • etsy_shops: export shops. Etsy only
  • etsy_transaction: export transactions. Etsy only
  • etsy_users: export users. Etsy only
  • orkut_post: export posts. Orkut only
  • orkut_scraps: export scraps. Orkut only
  • orkut_testimonials: export testimonials. Orkut only
  • orkut_makamakas: export makamakas. Orkut only
  • orkut_comments: export comments. Orkut only
  • orkut_videos: export videos. Orkut only
  • orkut_photos: export photos. Orkut only
  • orkut_users: export users. Orkut only
  • digg_diggs: export users. Digg only
  • digg_comments: export comments. Digg only
  • digg_followers: export followers. Digg only
  • digg_followings: export followings. Digg only
  • gplus_posts: export posts. Google+ only
  • gplus_reshares: export reshares. Google+ only
  • gplus_plusoners: export plusoners. Google+ only
  • gplus_resharers: export resharers. Google+ only
  • blogger_posts: export posts. Blogger only
  • blogger_comments: export comments. Blogger only
  • blogger_pages: export pages. Blogger only
  • blogger_search_terms: export search terms. Blogger only
  • blogger_users: export users. Blogger only
  • reddit_reddits: export reddits. Reddit only
  • reddit_comments: export comments. Reddit only
  • reddit_friends: export friends. Reddit only

Output

  • zip file: downloadable zip file with comma delimited files representing different aspects of account data.

https://api.socialreport.com/register.svc

Register new customers. Note that this API must be used over SSL and only accepts "POST" request.

Parameters

  • user.firstName: customer first name
  • user.lastName: customer last name
  • user.email: customer email
  • user.username: customer username
  • user.password: customer password
  • packageOption: plan. 1 - "Starter", 2 - "Business", 3 - "Agency", 4 - "Ultimate"
  • billing.firstName: billing first name
  • billing.lastName: billing last name
  • billing.address1: billing street address
  • billing.city: billing city
  • billingCountry: two letter custom code
  • billing.postCode: billing post code
  • payment.cardholderNamecardhold name
  • payment.numbercredit card number
  • payment.cvv2card's cvv code
  • expirationMonthcard's expiration month: January, Feburary, etc
  • expirationYearcard's expiration year: 2012, 2014, etc

Output

[
    {
        "status": "ok",
        "user_id": "595959532"
    }
]
                            

https://api.socialreport.com/customers.svc

Retrieve your customers. If you are an affiliate and/or have an integrated registration process - this method will allow you to retrieve all of your customers and their payment details.

Output

[
    {
        "id": "877272",
        "enabled": "no",
        "firstName": "Brian",
        "lastName": "Gordon",
        "subscription": {
            "plan": "Professional",
            "balance": "0",
            "expected": "0",
            "monthly": "39",
            "nextPaymentDate": "20111210",
            "payments": []
        },
        "created": "20111110"
    },
    {
        "id": "3311111",
        "enabled": "yes",
        "firstName": "Jason",
        "lastName": "Smith",
        "subscription": {
            "plan": "Professional",
            "balance": "39",
            "expected": "78",
            "monthly": "39",
            "nextPaymentDate": "20111210",
            "payments": [
                {
                    "date": "20110910",
                    "amount": "39",
                    "status": "ok"
                },
                {
                    "date": "20111010",
                    "amount": "39",
                    "status": "failed"
                }
            ]
        },
        "created": "20111109"
    }
]
                            

https://api.socialreport.com/agentCreate.svc

Create a new keyword search agent


Parameters

  • project: project identifier
  • name: agent name
  • scope: search scope. network - only in registered accounts, global - everywhere
  • selection: search criteria. and - all keywords, or - any keywords
  • keywords: keywords list with ~~~ delimiter

Output

  • id: unique agent identifier.
[
    {
        "id": "326"
    }

]
                            

https://api.socialreport.com/agents.svc

Get a list of all search agents for a project. Search agents allow you to search social space for keywords that interest you.

Parameters

  • project: project identifier

Output

  • id: unique keyword agent identifier.
  • name: agent name.
  • initialized: indicates if initial search has been completed.
[
    {
        "id": "65299",
        "name": "social media",
        "initialized": "yes"
    },
    {
        "id": "54321",
        "name": "social report",
        "initialized": "yes"
    }
]
                            

https://api.socialreport.com/agentModify.svc

Modify an existing keyword agent.

Parameters

  • agent: agent identifier
  • name: agent name
  • scope: search scope. network - only in registered accounts, global - everywhere
  • selection: search criteria. and - all keywords, or - any keywords
  • keywords: keywords list with ~~~ delimiter

Output

  • id: unique agent identifier.
[
    {
        "id": "464"
    }

]
                            

https://api.socialreport.com/authenticate.svc

Authenticates the user, generates single sign-on token. You can then use generate token direct your user to

https://[www.socialreport.com or white labeled domain]/sso.htm?token=generated_token

which will seamlessly log the user into his or her Social Report account. Note that if you are using a white labeled domain - you can substitute www.socialreport.com with your domain.

Generated tokens are only valid for 30 seconds once generated.

Parameters

  • user_id: user identifier

Output

[
    {
        "token": "0hokth7bh7rbbmravhabcam4uo27gx9cec46"
    }
]

https://api.socialreport.com/user.svc

Get a user information.

Parameters

  • id: user's identifier

Output

[
    {

        "firstName": "John",
        "lastName": "Smith",
        "email": "john.smith@test.com",
        "username": "john",
        "defaultLanguage": "en",
        "timezoneId": "America/Virgin",
        "currencyCode": "USD",
        "customization": "{"showNotifications":"yes",
                           "showAskUs":"yes",
                           "api_key":"user's_api_key",
                           "showNews":"yes",
                           "active":"yes",
                           "showUserProfile":"yes",
                           "language":"en",
                           "logo": "logo_image.png",
                           "name": "reseller's name",
                           "domain": "thedomain.com",
                           "affiliateCode": "welcome",
                           "whiteLabel":"yes"}"
    }
]

https://api.socialreport.com/user.svc

Retrieve complete information about user.

Parameters

  • id: user identifier or email: user email

Output

{
    "user": {
        "user_id": 43309756,
        "firstName": "John",
        "lastName": "Smith",
        "email": "john@gmail.com",
        "packageOption": 4,
        "username": "johnSmith",
        "company": "IBM",
        "defaultLanguage": "en",
        "timezoneId": "Europe/London",
        "currencyCode": "USD",
        "customization": {
            "api_key": "jghrkgfg4564r4fwkeff",
            "name": "SocialCompany",
            "domain": "socialcompany.com",
            "logoutLink": "socialcompany.com/logout.html",
            "language": "en",
            "email": "johnsmith@socialcompany.com",
            "affiliateCode": "social",
            "showAskUs": "yes",
            "showNews": "yes",
            "showUserProfile": "no",
            "showNotifications": "no",
            "logo": "socialcompany.jpg",
            "favicon": "socialcompany.ico",
            "active": "yes",
            "whiteLabel": "yes"
        }
    },
    "projects": {
        "owned": [
            {
                "id": 4645763,
                "name": "Facebook and Twitter"
            },
            {
                "id": 4643444,
                "name": "LinkedIn and Xing"
            }
        ]
        "accessible": [
            {
                "id": 6765554,
                "name": "Auto on Facebook",
                "permissions": {
                    "accounts": "yes",
                    "addAccount": "no",
                    "agents": "no",
                    "campaigns": "yes",
                    "contacts": "no",
                    "export": "yes",
                    "goals": "yes",
                    "reports": "yes",
                    "api": "no",
                    "notifications": "yes"
                }
            }
        ]
    }
}
]

https://api.socialreport.com/userCreate.svc

Create a new user.

Parameters

  • user.firstName: user's first name
  • user.lastName: user's last name
  • user.email: user's email
  • user.username: user's username
  • user.password: user's password
  • user.defaultLanguage: user's default language code (optional)
  • user.timezoneId: user's timezone identifier (optional)
  • user.currencyCode: user's currency code (optional)
  • packageOption: reseller's package option

Output

[
    {
        "status": "ok",
        "user_id":"1232245"
    }
]

https://api.socialreport.com/userUpdate.svc

Update an existing user.

Parameters

  • id: user's identifier
  • firstName: user's first name (optional)
  • lastName: user's last name (optional)
  • email: user's email (optional)
  • defaultLanguage: dashboard language code (optional)
  • timezoneId: user's timezone identifier (optional)
  • currencyCode: user's currency code (optional)
  • password: user's password (optional)
  • enabled: user's status. on - user can access to dashboard, off - user can't access to dashboard

Output

[
    {
        "status": "ok",
        "user_id": "12123"
    }
]

https://api.socialreport.com/customize.svc

Customize white label setup

Parameters

  • domain: your white label domain.
  • name: used through out the system - it replaces the term "Social Report"
  • signupLink: this is a link to what you would consider an 'onboarding' page on your site. Can be anything you wish. This link is available on the login screen.
  • logoutLink: once the user logs out - this is where we will take the user.
  • logoLink: this is the link that is attached to your logo (in case the user decides to click on it)
  • supportLink: if user has any questions, this is where he will be taken.
  • faqLink: link to a page with frequently asked questions.
  • language: dashboard language code
  • email: it is used for "Contact us" link and for any email notifications.
  • showAskUs: Zendesk driven ask us button - this gives you ability to show/hide it. yes - show button, no - hide button
  • showNews: should your users see Social Report news and feature alerts upon login. yes - show button, no - hide button
  • showUserProfile: you may wish to hide user's profile (My Account) for your users. This is useful if you are integrating with Social Report. yes - show button, no - hide button
  • showNotifications: disable ability by the user to opt-in/out from notifications. yes - show button, no - hide button
  • logo: this is where you would need to upload your logo. Do note that dimensions of the logo have to be exact.
  • favicon: upload a customized favicon. Favicon is a small graphic that is displayed in the browser tab.

Output

[
    {
        "status": "ok"
    }
]

https://api.socialreport.com/publicationDetail.svc

Get a publication information.

Parameters

  • id: publication's identifier

Output

{
    "id": 1499,
    "project": 111117,
    "name": "Test twitter adn Facebook",
    "status": "published",
    "created_utc": 1379323259000,
    "schedule": {
        "20130916 12:23 +0300": {
            "id": 1481,
            "date_utc": 1379323380000,
            "message": "Microsoft spent billions of dollars to purchase Nokia..."
        },
        "20130916 12:33 +0300": {
            "id": 1482,
            "date_utc": 1379323999000,
            "message": "Microsoft spent billions of dollars to purchase Nokia..."
        }
    },
    "roi": {
        "campaignCost": 2,
        "conversionValue": 4,
        "conversionCost": 6
    },
    "accounts": [
        275,
        17669
    ],
    "publications": [
        {
            "account": 17669,
            "date_utc": 1379324237000,
            "schedule_id": 1482,
            "message": "Microsoft spent billions of dollars to purchase Nokia...",
            "post_id": "160542717403351_213408385450117",
            "post_url": "http://www.facebook.com/160542717403351/posts/213408..."
        },
        {
            "account": 275,
            "date_utc": 1379324232000,
            "schedule_id": 1482,
            "message": "Microsoft spent billions of dollars to purchase Nokia...",
            "post_id": "379539449774104576",
            "post_url": "http://twitter.com/NovikNG/statuses/379539449774104576"
        },
        {
            "account": 17669,
            "date_utc": 1379323380000,
            "schedule_id": 1481,
            "message": "Microsoft spent billions of dollars to purchase Nokia...",
            "post_id": "160542717403351_213407112116911",
            "post_url": "http://www.facebook.com/160542717403351/posts/213407..."
        }
    ],
    "result": {
        "responses": 41,
        "conversions": 12
    }
}
    
Sign up Now get started today!