Social Graph¶

API: Set Token¶

URL: {BASE_URL}/app/<APP_ID>/social/graph/<MODE>/<USER_ID>/token

Request Method: HTTP POST

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
MODE	Yes	String	The mode for user ID interpretation
USER_ID	Yes	String	The user ID for whom the token is to be set.
token	Yes	Alpha-numeric	The access token issued by the social media platform.
expiry	Yes	Numeric	The expiry time of the token - after which using this token is not possible. Units are in seconds.
fmt	No	String	One of (json \| xml) - the format of output

If successful, the output will contain status=ok state - of course, in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

If any of the two params - token and expires - is missing, the API will generate an error.

Example¶

Note

Sensitive information is masked out in the following examples.

1. Error - when ‘token’ is missing (this takes priority - since without the token, the ‘expires’ parameter makes no sense):

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/social/graph/fb/kunalg/token"

Output:

{
    "status": "error",
    "error": {
        "message": "Token not passed",
        "code": -20002,
        "code_str": "E_MISSING_TOKEN"
    }
}

2. Error - when ‘expires’ is missing:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "token=test_token" \
    "http://api.playblazer.com/v1/app/1/social/graph/fb/kunalg/token"

Output:

{
    "status": "error",
    "error": {
        "message": "expires not passed",
        "code": -20003,
        "code_str": "E_MISSING_EXPIRES"
    }
}

API: Get friend-list¶

URL: {BASE_URL}/app/<APP_ID>/social/graph/<MODE>/<USER_ID>

Request Method: HTTP GET

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
MODE	Yes	String	The mode for user ID interpretation
USER_ID	Yes	String	The user ID for whom the social graph is to be retrieved.
show	No	String	The filtering parameter - specifies what kind of profiles/friends to show. Possible values: all - include all profiles in the output (default) registered - include only friend profiles which are already registered in the application unregistered - include only friend profiles which are NOT registered in the application
src	No	String	The source of the graph - to return entries only from a specific social graph. Possible values: all - select entries from all connected graphs (default) fb - select entries only from FB graph. google - select entries only from G+ graph. phonebook - select entries only from the phonebook graph.
fmt	No	String	One of (json \| xml) - the format of output

In case of error, the output will contain status=error and error details encoded as explained earlier.

If successful, the output will contain status=ok state along with a list of friends and their attributes as returned by the social media platform - of course, in the format that is specified in the API call.

Example¶

Note

Sensitive information is masked out in the following examples.

Note

If the user has multiple social IDs associated with the profile and if we have access to the social graphs from multiple sources, those will be returned in the combined output and the source of the entry is tagged with src attribute indicating the social graph from which the entry was gathered.

Note

We now support phonebook as a social graph as well. You’d need to call the API: Upload Phonebook from the Social Graph module to upload the user’s phonebook.

Warning

Since email and phone no. of the user are sensitive information, they will not be returned in the social graph output - so that it’s not harvested by spammers.

Instead, we return the playblazer_id - if available, or the phonebook_id which identifies the user entry in the uploaded phonebook.

null value for playblazer_id indicates that the user does not exist in the Playblazer database. The status for the user will be unregistered.

1. Successful call:

URL Call:

curl "http://api.playblazer.com/v1/app/1/social/graph/fb/kunalg?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
    "status": "ok",
    "friends": [
        {
            "status": "offline",
            "picture": {
                "data": {
                    "url": "http://profile.ak.fbcdn.net/static-ak/rsrc.php/v2/yo/r/UlIqmHJn-SK.gif",
                    "is_silhouette": true
                }
            },
            "first_name": "Kunal",
            "name": "Kunal D.",
            "src": "fb",
            "id": "xxxxxxxxxxxxxxx",
            "playblazer_id": 351
        },
        {
            "status": "unregistered",
            "picture": {
                "data": {
                    "url": "http://profile.ak.fbcdn.net/static-ak/rsrc.php/v2/yo/r/UlIqmHJn-SK.gif",
                    "is_silhouette": false
                }
            },
            "first_name": "Neetu",
            "name": "Neetu G.",
            "src": "fb",
            "id": "xxxxxxxxx",
            "playblazer_id": null
        },
        {
            "status": "unregistered",
            "picture": {
                "data": {
                    "url": "http://profile.ak.fbcdn.net/static-ak/rsrc.php/v2/yo/r/UlIqmHJn-SK.gif",
                    "is_silhouette": false
                }
            },
            "first_name": "Nikhil",
            "name": "Nikhil S.",
            "src": "fb",
            "id": "xxxxxxxxx",
            "playblazer_id": null
        },
        {
            "status": "unregistered",
            "picture": {
                "data": {
                    "url": "http://profile.ak.fbcdn.net/static-ak/rsrc.php/v2/yo/r/UlIqmHJn-SK.gif",
                    "is_silhouette": false
                }
            },
            "first_name": "Anteema",
            "name": "Anteema A.",
            "src": "fb",
            "id": "xxxxxxxxxxxxxxxx",
            "playblazer_id": null
        },
        {
            "status": "online",
            "src": "phonebook",
            "first_name": "Kunal",
            "last_name": "Gangakhedkar",
            "picture": {
                "data": {
                    "url": null
                }
            },
            "playblazer_id": 297
        },
        {
            "status": "unregistered",
            "src": "phonebook",
            "first_name": "Nikhil",
            "last_name": "Soman",
            "picture": {
                "data": {
                    "url": null
                }
            },
            "playblazer_id": null
        }
    ]
}

API: Upload Phonebook¶

URL: {BASE_URL}/app/<APP_ID>/social/graph/<MODE>/<USER_ID>/phonebook

Request Method: HTTP POST

Required HTTP Header: Content-Type: application/json

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
MODE	Yes	String	The mode for user ID interpretation
USER_ID	Yes	String	The user ID whose phone book is being uploaded.
phonebook	Yes	JSON Array	List of phone book entries (explained below).
fmt	No	String	One of (json \| xml) - the format of output

If successful, the output will contain status=ok state - of course, in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Each entry in the phonebook array has the following fields:

first_name

last_name

phoneno

image_url (optional)

Note

The phone no. must be in the E.164 format - that is a ‘+’ sign followed by the country code followed by the national phone number.

Avoid using any separators between numbers - like spaces, hyphens/dashes or brackets.

The output will contain the following entries along with the “status” field:

connected - the list of users who are already connected (i.e. already available in the phonebook graph)

existing_users - the list of users who are already registered with the Playblazer platform and have the phone no. connected to their profile.

new_users - the list of new entries created in the phonebook graph.

errors - list of entries which contained some form of errors (currently, only invalid phone nos. - i.e. phone nos. not in E.164 format)

Example¶

URL Call:

curl -X POST \
    -H "Content-Type: application/json"
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "phonebook=[ { \"first_name\": \"John\", \"last_name\": \"Doe\",
                        \"phoneno\": \"+15552337865\" },
                    { \"first_name\": \"Nikhil\", \"last_name\": \"Soman\",
                        \"phoneno\": \"+911234567890\" },
                    { \"first_name\": \"John\", \"last_name\": \"Gilbert\",
                        \"phoneno\": \"272\" } ]"
    "http://api.playblazer.com/v1/app/1/social/graph/fb/kunalg/phonebook"

Output:

{
    "status": "ok",
    "connected": [
        {
            "first_name": "Nikhil",
            "last_name": "Soman",
            "phoneno": "+911234567890"
        }
    ],
    "existing_users": [],
    "new_users": [
        {
            "first_name": "John",
            "last_name": "Doe",
            "phoneno": "+15552337865"
        }
    ],
    "errors": [
        {
            "error": "invalid phone no.",
            "entry": {
                "first_name": "John",
                "last_name": "Gilbert",
                "phoneno": "272"
            }
        }
    ]
}