ident engine

API Documentation

Identity API

The identity API takes the URL of a public profile page on a social media site. This could be on Twitter, Google+, Flickr, Lanyrd or any other web profile page. It then searches for links to other identities related to that individual and returns a JSON graph. Alternatively, the API will also take a webfinger address to start the search.

http://identengine.com/api/identities/?identifier=

  1. A URL as an identifier – http://twitter.com/glennjones
    /api/identities/?identifier=http%3A%2F%2Ftwitter.com%2Fglennjones/
  2. A webfinger address as an identifier – glennjonesnet@gmail.com
    /api/identities/?identifier=glennjonesnet%40gmail.com

JSON returned

{
  "identities": [{
      "name": "Github",
      "domain": "github.com",
      "matchedUrl": "http://github.com/glennjones",
      "userName": "glennjones",
      "sgn": "sgn://github.com/?ident=glennjones",
      "endPoints": [
        {
          "schema": "Atom",
          "contentType": "Activity",
          "mediaType": "Atom",
          "url": "https://github.com/glennjones.atom"
        },
        {
          "schema": "hCard",
          "contentType": "Profile",
          "mediaType": "Html",
          "url": "https://github.com/glennjones"
        },
        {
          "schema": "XFN",
          "contentType": "Services",
          "mediaType": "Html",
          "url": "https://github.com/glennjones"
        }
      ],
      "frequency": 2,
      "icon16": "http://github.com/favicon.ico"
  }],
  "domainsNotMapped": [{
    "url": "http://glennjones.net/",
    "frequency": 7
  }],
  "urlsNotParsed": [
    "http://www.youtube.com/channel/UCLBkAp8Q5PP_zzBjrRjb_PA"
  ],
  "commonUserName": "glennjones",
  "highestFrequencySite": "http://glennjones.net/"
}

Profiles API

The profiles API takes the URL of a public profile page on a social media site like the Identity API. This API takes the process one-step further once it has searched for identities it parsers and returns whatever profiles data it can find. The profiles are also combined together to provide a more complete aggregated profile. Alternatively, the API will also take a webfinger address to start the search.

http://identengine.com/api/identities/profiles/?identifier

  1. A URL as an identifier – http://twitter.com/glennjones
    /api/identities/profiles/?identifier=http%3A%2F%2Ftwitter.com%2Fglennjones
  2. A webfinger address as an identifier – glennjonesnet@gmail.com
    /api/identities/profiles/?identifier=glennjonesnet%40gmail.com

JSON returned

{
  "profiles": [
    "profile": {
      "fn": "Glenn Jones",
      "url": [
        "http://glennjones.net",
        "https://github.com/glennjones"
      ],
      "label": ["Brighton, UK"]
    },
    "identity": {
        "name": "Github",
        "domain": "github.com",
        "matchedUrl": "http://github.com/glennjones",
        "userName": "glennjones",
        "sgn": "sgn://github.com/?ident=glennjones",
        "endPoints": [
          {
            "schema": "Atom",
            "contentType": "Activity",
            "mediaType": "Atom",
            "url": "https://github.com/glennjones.atom"
          },
          {
            "schema": "hCard",
            "contentType": "Profile",
            "mediaType": "Html",
            "url": "https://github.com/glennjones"
          },
          {
            "schema": "XFN",
            "contentType": "Services",
            "mediaType": "Html",
            "url": "https://github.com/glennjones"
          }
        ],
        "frequency": 2,
        "icon16": "http://github.com/favicon.ico"
    }
  ],
  "combinedProfile": {
   "fn": "Glenn Jones",
    "url": [
      "http://glennjones.net",
      "https://github.com/glennjones"
    ],
    "label": ["Brighton, UK"]
    "commonUserName": "glennjones",
    "highestFrequencySite": "http://glennjones.net/"
    "accounts": [{
      "name": "Github",
      "domain": "github.com",
      "userName": "glennjones",
      "sgn": "sgn://github.com/?ident=glennjones",
      "icon16": "http://github.com/favicon.ico",
      "frequency": 2,
      "profileUrl": "https://github.com/glennjones"
    }] 
  }
}

Additional querystring options

There are two querystring parameters that can be used with the API calls. The first is a JSONP callback parameter which wraps the returning JSON in the function name you provide.

The second is usecache, this turns on or off the caching of results. The Ident Engine caches results by default you may want to request it to do a new search and refresh its results by setting usecache=false. This can slow down the API call, which may last many seconds.

Errors

If the URL and webfinger address you provide in anyway fails to parse the API will record an error within the returned JSON. An error is returned as a string message.

{
  ...
  error: "http error: 404 (Not Found) - http://twitter.com/statuses/user_timeline/chrisnewtn.rss",
  ...
}  

Warnings

After the first web address has been parsed without error and any other errors that happen are recorded as warnings within the returned JSON. This allows the parser to complete and return data rather than stopping, much like how a HTML page is parsed in a browser. Any warnings are returned as an array of string messages.

{
  ...
  warnings: [
    "http error: 404 (Not Found) - http://twitter.com/statuses/user_timeline/chrisnewtn.rss"
  ],
  ...
}  

Rate limiting

The Ident Engine API is not backed by a commercial entity, as such the API is rate limited and you can only make 1000 requests a day. If you wish to make a large number of requests you can download the libraries, which the API is built on, and host your own version.

Utility - Mapping API

The mapping API does not search for interlinked identities like the other API endpoints. Instead it is provided so that you can convert a comma delimited list of URLs or SGNs into a mapping.

/api/mapping/?identifiers

  1. Comma delimited list of URLs – http://twitter.com/glennjones
    /api/mapping/?identifiers=http%3A%2F%2Ftwitter.com%2Fglennjones/
  2. Comma delimited list of SGNs – sgn://twitter.com/?ident=glennjones
    /api/mapping/?identifiers=sgn%3A%2F%2Ftwitter.com%2F%3Fident%3Dglennjones/