Quick links

Methods

Available formats

JSON

Socialbel API Documentation

Methods

Introduction

The Socialbel API provides a simple way to request data from Socialbel.com via HTTP requests.

Overview

This is a beta version of the API. All methods, data formats, error codes and outputs can be changed in the future

Data Types

Term

Property	Type	Description
`id`	String	Term id
`text`	String	Term contents
`description`	String	Description about the term
`thumbsup`	Number	Number of positive votes
`thumbsdown`	Number	Number of negative votes
`parent`	String	When it's a translation, parent has the parent term id
`istranslation`	Boolean	Is it a Term or a Translation?
`created`	Date	Created date on ISO 8601 format
`updated`	Date	Updated date on ISO 8601 format
`language`	Object	What language this term was created. See Language for more information
`user`	Object	Who create this. See User for more information

User

Property	Type	Description
`id`	String	username
`name`	String	Real name
`profile`	String	User's Profile URL
`avatar`	String	Photo or image
`language`	String	Native language. See Language for more information

Language

Property	Type	Description
`code`	String	Language code like "en", "pt_BR" or "es"
`name`	String	Language name like "English", "Brazilian Portuguese" or "Spanish"

Result Data Formats

All API requests output data on these formats ("json" is default):

Name	Key	Description	Site
JSON	`json`	JSON (JavaScript Object Notation) is a lightweight data-interchange format	json.org
XML	`xml`	Extensible Markup Language (XML) is a simple, very flexible text format derived from SGML Not implemented yet	w3.org/XML

Example Call

http://socialbel.com/api/user/socialbel?format=json

Common arguments

Name	Key	Description
Format	`format`	Data format. See Result Data Formats for more information
Page	`page`	Current page (default 1)
Count	`count`	Items per page (default 20, max 100)
Callback	`callback`	When callback is defined and format is equal to "json", all output is returned like a funciton call, example: http://socialbel.com/api/search/?query=socialbel&callback=myFunctionName `myFunctionName([{"id":"ABKxWQXJNU", ... }]);`

Example Call

http://socialbel.com/api/user/socialbel?count=2&page=5

Error messages

Code	Name
0	An unknown error occurred
1	Invalid format
2	No method specified
3	Missing required argument for this method
4	No results were returned

Methods

`/api/search/` - Search

Search for terms and translations. Parameters:

Name	Key	Description
Query (required)	`query`	Query string
Username	`user`	Restrict your search for only terms from user
Language	`language`	Restrict your search for only terms in that language. Use only language code for now.

Result Structure

[] Array of Terms

Example Call

http://socialbel.com/api/search/?query=i+love+you

Example Response

[
  {
    "id":"uckcaTlxsP",
    "text":"I love you",
    "description":"",
    "thumbsup":0,
    "thumbsdown":0,
    "parent":null,
    "istranslation":false,
    "created":"2009-03-06T13:13:03-03:00",
    "updated":"2009-03-06T13:13:03-03:00",
    "language":{
      "code":"en",
      "name":"English"
    },
    "user":{
      "id":"LucasAraujo",
      "name":"Lucas Neves de Araujo",
      "profile":"http:\/\/socialbel.com\/user\/LucasAraujo",
      "avatar":"http:\/\/www.gravatar.com\/avatar\/be18247ed9bb85699a12e0136d4cceda?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
      "language":{
        "code":"pt_BR",
        "name":"Brazilian Portuguese"
      }
    }
  },
  {
    "id":"iytWubrotu",
    "text":"Je t'aime.",
    "description":"",
    "thumbsup":1,
    "thumbsdown":0,
    "parent":"uckcaTlxsP",
    "istranslation":true,
    "created":"2009-03-06T18:06:43-03:00",
    "updated":"2009-03-06T18:06:43-03:00",
    "language":{
      "code":"fr",
      "name":"French"
    },
    "user":{
      "id":"toshielitzin",
      "name":"Toshie Takahashi",
      "profile":"http:\/\/socialbel.com\/user\/toshielitzin",
      "avatar":"http:\/\/www.gravatar.com\/avatar\/5e439cf6073267f297d4dabd461ea49c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
      "language":{
        "code":"ja",
        "name":"Japanese"
      }
    }
  }
]

`/api/user/[USERNAME]` - Fetch user information

Replace [USERNAME] with the user's username to retrieve him/her information and translations

Result Structure

user {} User Data Type
translations [] Array of Terms

Example Call

http://socialbel.com/api/user/socialbel

Example Response

{
  "user":{
    "id":"socialbel",
    "name":"Socialbel.com",
    "profile":"http:\/\/socialbel.com\/user\/socialbel",
    "avatar":"http:\/\/www.gravatar.com\/avatar\/cae148060443487fa8017f4872f6dc5c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
    "language":{
      "code":"en",
      "name":"English"
    }
  },
  "translations":[
    {
      "id":"bDCHivPLBg",
      "text":"Admin",
      "description":"Abbreviation to Administrator",
      "thumbsup":0,
      "thumbsdown":0,
      "parent":null,
      "istranslation":false,
      "created":"2009-03-05T12:25:16-03:00",
      "updated":"2009-03-05T12:25:16-03:00",
      "language":{
        "code":"en",
        "name":"English"
      },
      "user":{
        "id":"socialbel",
        "name":"Socialbel.com",
        "profile":"http:\/\/socialbel.com\/user\/socialbel",
        "avatar":"http:\/\/www.gravatar.com\/avatar\/cae148060443487fa8017f4872f6dc5c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
        "language":{
          "code":"en",
          "name":"English"
        }
      }
    },
    {
      "id":"Wnmk_LIYrS",
      "text":"Administrator",
      "description":"One who administers",
      "thumbsup":0,
      "thumbsdown":0,
      "parent":null,
      "istranslation":false,
      "created":"2009-03-05T12:23:07-03:00",
      "updated":"2009-03-05T12:23:07-03:00",
      "language":{
        "code":"en",
        "name":"English"
      },
      "user":{
        "id":"socialbel",
        "name":"Socialbel.com",
        "profile":"http:\/\/socialbel.com\/user\/socialbel",
        "avatar":"http:\/\/www.gravatar.com\/avatar\/cae148060443487fa8017f4872f6dc5c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
        "language":{
          "code":"en",
          "name":"English"
        }
      }
    }
  ]
}

`/api/term/[TERM_ID]` - Fetch term information

Replace [TERM_ID] with the term's id to retrieve translations

Result Structure

term {} Term Data Type
translations [] Array of Terms

Example Call

http://socialbel.com/api/term/bDCHivPLBg/

Example Response

{
  "term":{
    "id":"bDCHivPLBg",
    "text":"Admin",
    "description":"Abbreviation to Administrator",
    "thumbsup":0,
    "thumbsdown":0,
    "parent":null,
    "istranslation":false,
    "created":"2009-03-05T12:25:16-03:00",
    "updated":"2009-03-05T12:25:16-03:00",
    "language":{
      "code":"en",
      "name":"English"
    },
    "user":{
      "id":"socialbel",
      "name":"Socialbel.com",
      "profile":"http:\/\/socialbel.com\/user\/socialbel",
      "avatar":"http:\/\/www.gravatar.com\/avatar\/cae148060443487fa8017f4872f6dc5c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
      "language":{
        "code":"en",
        "name":"English"
      }
    }
  },
  "translations":[
    {
      "id":"iltDNvLZID",
      "text":"\u7ba1\u7406\u8005",
      "description":"",
      "thumbsup":0,
      "thumbsdown":0,
      "parent":"bDCHivPLBg",
      "istranslation":true,
      "created":"2009-03-06T16:06:26-03:00",
      "updated":"2009-03-06T16:06:26-03:00",
      "language":{
        "code":"ja",
        "name":"Japanese"
      },
      "user":{
        "id":"toshielitzin",
        "name":"Toshie Takahashi",
        "profile":"http:\/\/socialbel.com\/user\/toshielitzin",
        "avatar":"http:\/\/www.gravatar.com\/avatar\/5e439cf6073267f297d4dabd461ea49c?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
        "language":{
          "code":"ja",
          "name":"Japanese"
        }
      }
    },
    {
      "id":"DqMzMXLDtr",
      "text":"Admin",
      "description":"",
      "thumbsup":0,
      "thumbsdown":0,
      "parent":"bDCHivPLBg",
      "istranslation":true,
      "created":"2009-03-05T12:27:45-03:00",
      "updated":"2009-03-05T12:27:45-03:00",
      "language":{
        "code":"pt_BR",
        "name":"Brazilian Portuguese"
      },
      "user":{
        "id":"maopequena",
        "name":"Lizandra Silva",
        "profile":"http:\/\/socialbel.com\/user\/maopequena",
        "avatar":"http:\/\/www.gravatar.com\/avatar\/85a43543d4d6fca09c186e9a2dba932a?d=http%3A%2F%2Fsocialbel.com%2Fimages%2Fdefault_avatar.png&s=80",
        "language":{
          "code":"pt_BR",
          "name":"Brazilian Portuguese"
        }
      }
    }
  ]
}

`/api/update/` - Create or update a term

Not implemented yet

Quick links

Available formats

Socialbel API Documentation

Table of Contents

Introduction

Overview

Data Types

Term

User

Language

Result Data Formats

Example Call

Common arguments

Example Call

Error messages

Methods

/api/search/ - Search

Result Structure

Example Call

Example Response

/api/user/[USERNAME] - Fetch user information

Result Structure

Example Call

Example Response

/api/term/[TERM_ID] - Fetch term information

Result Structure

Example Call

Example Response

/api/update/ - Create or update a term

`/api/search/` - Search

`/api/user/[USERNAME]` - Fetch user information

`/api/term/[TERM_ID]` - Fetch term information

`/api/update/` - Create or update a term