Documentation

The API is accessed by making HTTP REST requests to http://api.qwerly.com. Please set the user agent header to something appropriate for your application. Other than that, no special headers are required. If you would like to receive Facebook data, you must connect your Facebook account (read more).

GET Parameters

api_key

Required.

Your API key should be appended to all calls in the form:

http://api.qwerly.com/v1/<method>?api_key=<YOUR_KEY>

callback

Optional.

If you add a callback parameter, the response will be wrapped in a function call (as JSONP), like this:

http://api.qwerly.com/v1/facebook/222632?callback=jsonHandler

jsonHandler({
  "profile":{
    "facebook_id":"222632",
    "facebook_username":"marissamayer",
    "name":"Marissa Mayer",
    "services":[
      ...
    ]
  },
  "status":200
})

Note that if callback is set, the HTTP status will always be set to 200 regardless of the real status (which you can still check in the 'status' field of the response).

request_id

Optional.

If you add a request_id parameter, it will be passed to the response so that you can identify which request matches which response:

http://api.qwerly.com/v1/facebook/222632?request_id=123456

{
  "profile":{
    "facebook_id":"222632",
    "facebook_username":"marissamayer",
    "name":"Marissa Mayer",
    "services":[
      ...
    ]
  },
  "request_id":"123456",
  "status":200
}

user_id & account_id

Optional.

If you have several users who have connected their Facebook or other third-party accounts to allow lookups via Qwerly, you should set the user_id and or account_id parameter that specifies on behalf of which user you are making the request. This ensures that privacy settings are preserved. Read more below.

Actions

Profile lookup actions look up a person given some kind of identifier. If we have all required data, you will get a "200 OK" response with JSON data like this:

http://api.qwerly.com/v1/twitter/dhh

{
  "profile": {
    "location": "Chicago, USA",
    "name": "DHH",
    "twitter_username": "dhh",
    "website": "http://www.loudthinking.com",
    "public_url": "http://qwerly.com/twitter/dhh",
    "services": [
      { "type": "friendfeed","url": "http://friendfeed.com/dhh","username": "dhh" },
      { "type": "github","url": "http://github.com/dhh","username": "dhh" },
      { "type": "twitter","url": "http://twitter.com/dhh","username": "dhh" },
      { "type": "klout","url": "http://klout.com/dhh","username": "dhh" }
    ]
  },
  "status": 200
}

If we don't have the profile in our database yet, we need to import it first; in this case, you will get a "202 Accepted" response and you'll be asked to retry. Please wait 24 hours between the requests.

Note: some data that takes longer to import will be added even after you receive the 200 OK response – so if you cache the results in your own database, make sure to refresh it periodically.

If we determine that a user with the given identifier doesn't exist, you will get a "404 Not Found" response.

Profile lookups

• Twitter username: /v1/twitter/<username>
• Facebook ID: /v1/facebook/<id>
• Facebook username: /v1/facebook/username/<username>
• Email address: /v1/email/<email>

Service lookups

For each of the actions that return a profile with links there's a corresponding method that only returns the links without the profile data. The URLs are created by appending /services to the end:

• Twitter username: /v1/twitter/<username>/services
• Facebook ID: /v1/facebook/<id>/services
• Facebook username: /v1/facebook/username/<username>/services
• Email address: /v1/email/<email>/services

Everything (status codes etc.) works the same as in the original requests, except you get a 'services' field instead of 'profile' field, e.g.:

http://api.qwerly.com/v1/twitter/dhh/services

{
  "services": [
    { "type": "twitter", "url": "http://twitter.com/dhh", "username": "dhh" },
    { "type": "friendfeed", "url": "http://friendfeed.com/dhh", "username": "dhh" },
    { "type": "github", "url": "http://github.com/dhh", "username": "dhh" },
  ],
  "status": 200
}

Note that if the data needs to be imported first (and you get a 202 response), the services-only request may be ready a bit faster than the full profile request.

Batch priming

To avoid the overhead of using an API call for every potential request you can "prime" a group of identifiers by POSTing them to our /prime/ action. Here's an example that would work on a host with curl installed:

cat list-of-twitter-users.txt | POST "http://api.qwerly.com/v1/prime/twitter?api_key=xxx"

The ids should be listed in the file, one per line (where a line-ending is a unix style \n). The above might yield something along the lines of:

{
  "one": 200,
  "two": 202,
  "three": 202,
  "four": 200,
  "processed": {
    "200": 2,
    "202": 2,
    "404": 0,
    "total": 4
  }
}

This interface is limited, by api_key, to one request every 10 seconds. You can post up to 100 emails at a time.

The number associated in the results with the ids are the HTTP responses you would get should you have requested them with a normal GET at the same time.

Batch lookups

For each of the profile lookup actions you can pass up to 10 identifiers separated with commas – in this case, the application will look up all given profiles and return a single response with their data.

The way the group response looks is that:

For every identifier you requested, there's an entry in the JSON with the identifier as the key and a standard response (as for single user lookups) as the value – together with a status that tells if that user is downloaded, not found or if the import is in progress there's a separate 'status' field that contains the status of the whole request the rules for determining the global status are:

If any of the profiles has status 202, the global status is set to 202 if all profiles have status 404, the global status is set to 404 otherwise (if some profiles are found and some aren't) the response has status 200 Example:

http://api.qwerly.com/v1/twitter/tweetie,dropbox,macruby

{
  "tweetie": {
    "profile": {
      "description": "Follow @mobilesupport. We can help you!.",
      "location": "Twitter HQ",
      "name": "Tweetie",
      "twitter_username": "tweetie",
      "website": "http://www.atebits.com/software/tweetie/",
      "services": [
        { "type": "twitter", "url": "http://twitter.com/tweetie", "username": "tweetie" },
        { "type": "klout", "url": "http://klout.com/tweetie", "username": "tweetie" }
      ]
    },
    "public_url": "http://qwerly.com/twitter/tweetie",
    "status": 200
  },
  "dropbox": {
    "profile": {
      "description": "File syncing, sharing and backup that rocks. Follow @Dropboxops for status!",
      "location": "sf, ca",
      "name": "Dropbox",
      "twitter_username": "dropbox",
      "website": "http://dropbox.com",
      "services": [
        { "type": "twitter", "url": "http://twitter.com/dropbox", "username": "dropbox" },
        { "type": "google_profiles", "url": "http://www.google.com/profiles/dropboxmic", "username": "dropboxmic" },
        { "type": "klout", "url": "http://klout.com/dropbox", "username": "dropbox" }
      ]
    },
    "public_url": "http://qwerly.com/twitter/dropbox",
    "status": 200
  },
  "macruby": {
    "profile": {
      "description": "MacRuby News!",
      "location": "Planet Earth",
      "name": "MacRuby",
      "twitter_username": "macruby",
      "website": "http://macruby.org",
      "services": [
        { "type": "twitter", "url": "http://twitter.com/macruby", "username": "macruby" },
        { "type": "github", "url": "http://github.com/MacRuby", "username": "macruby" },
        { "type": "klout", "url": "http://klout.com/macruby", "username": "macruby" }
      ]
    },
    "public_url": "http://qwerly.com/twitter/macruby",
    "status": 200
  },
  "status": 200
}

Facebook Data

To receive data from Facebook, Facebook's terms of service and policies require each end user accessing any Facebook data to OAuth with their personal account.

You and your end users can do so by going to:

http://qwerly.com/facebook/login?api_id=<mashery_username>

Please set the api_id to your Mashery username (the handle which you use to log in to Qwerly). This will connect it to your API key and save your Facebook access token in the Qwerly application.

If you have more than one end user connecting their Facebook account to your API key, you should set a user_id. This can be any string identifying the end user which will be accessing data from Facebook and ensures that Facebook privacy settings are respected. Finally, if you have several sub-groups of users, you may also set an account_id. If you set an account_id, you must specify a user_id. The full link with user_id and account_id set is

http://qwerly.com/facebook/login?api_id=<mashery_username>&user_id=<user_id>&account_id=<account_id>

Note that, if set, the user_id and account_id should be appended as GET parameters on every request to the Qwerly API.