Open Badges Directory

Worldwide Directory of Open Badges

Follow me on GitHub

Retrieve Badges (API)

The directory API endpoints allow you to retrieve currently indexed badges. At the moment the directory stores badge classes only, although further developments are under discussion.

To have your badges indexed by the directory or to find out more about the project, see the home page.

With the API, you can retrieve:

  • badges matching search parameters
    • including full text search, tags, badge or issuer name
  • badges recently added to the directory
  • specific badges using the badge class location
  • badge tags
    • which you can then use to search for badges

The API uses ElasticSearch.

The Directory API endpoints return JSON-formatted badge class data, which your site or application can then parse and present in any way you choose. The badge class data includes information about what a badge represents, who issued it and the criteria for earning it.

You can see the badge class information for badges currently in the directory, presented within a Web interface, using the example browser. For more information about Badge Classes in Open Badges, see the specification documents.

API Explorer

For an interactive experience with the API, visit the API Explorer. This will load up a swagger-powered interface that can directly invoke the API endpoints listed below.

API

The API provides various endpoints for retrieving badge classes currently indexed by the directory.

Search

Returns all badges matching the specified search parameters.

Available Request Parameters

 Parameter   Type   Description 
 q   string   text to use in full text search of badges 
 tags   string   comma-separated list of badge tags to match in returned badges - multiple tags create AND condition 
 name   string   name of badge class to return 
 issuer   string   name of issuer whose badges should be returned 
 limit   integer   how many results to return per page (default 10, max 100) 
 page   integer   page of results to return 

At least one search parameter is required.

Expected Request

GET /search?q=text-to-find&tags=tag1,tag2&name=badge-name&issuer=issuer-name

Example Requests

/search?q=maker
/search?tags=technology
/search?name=open%20badges%20explorer
/search?issuer=achievery
/search?q=delegate&issuer=achievery

cURL Example

curl http://directory.openbadges.org/search?q=maker

Expected Response

JSON-structured array of badge classes matching the search parameters, or an empty array if no matching badges are returned.

{
  "data": [
    {
      "name": "Badge Name",
      "description": "Badge description.",
      "image": "http://issuersite.com/badge.png",
      "tags": [
        "tag1",
        "tag2",
        ...
      ],
      "issuer": "http://issuersite.com",
      "criteria": "http://issuersite.com/criteria.html",
      "alignment": [
        {
          "name": "Alignment Name",
          "url": "http://alignmentsite.com",
          "description": "Alignment desription."
        }
      ],
      "_directory": {
        "_location": "http://issuersite.com/badgeclass",
        "_valid": true,
        "_timestamp": 1409852679994
      },
      "issuerResolved": {
        "name": "Issuer Name"
      }
    },
    {
      "name": "Badge Name",
      "description": "Badge description.",
      ...
    },
    ...
  ]
}

Response Structure

  • data [ ]
    • name
    • description
    • image
    • tags [ ]
    • issuer
    • criteria
    • alignment [ ]
      • name
      • url
      • description
    • _directory
      • _location
      • _valid
      • _timestamp
    • issuerResolved
      • name

Potential Errors

{
    "code": "BadRequestError",
    "message": "You must specify arguments to execute a search"
}

For more on the /search endpoint, see Search For Badges.

Recent

Returns all recently indexed badges.

Available Request Parameters

NONE

Expected Request

GET /recent

cURL Example

curl http://directory.openbadges.org/recent

Expected Response

JSON-structured array of badge classes recently indexed by the directory.

{
  "data": [
    {
      "name": "Badge Name",
      "description": "Badge description.",
      "image": "http://issuersite.com/badge.png",
      "tags": [
        "tag1",
        "tag2",
        ...
      ],
      "issuer": "http://issuersite.com",
      "criteria": "http://issuersite.com/criteria.html",
      "alignment": [
        {
          "name": "Alignment Name",
          "url": "http://alignmentsite.com",
          "description": "Alignment desription."
        }
      ],
      "_directory": {
        "_location": "http://issuersite.com/badgeclass",
        "_valid": true,
        "_timestamp": 1409852679994
      },
      "issuerResolved": {
        "name": "Issuer Name"
      }
    },
    {
      "name": "Badge Name",
      "description": "Badge description.",
      ...
    },
    ...
  ]
}

Response Structure

  • data [ ]
    • name
    • description
    • image
    • tags [ ]
    • issuer
    • criteria
    • alignment [ ]
      • name
      • url
      • description
    • _directory
      • _location
      • _valid
      • _timestamp
    • issuerResolved
      • name

Potential Errors

NONE

For more on the /recent endpoint, see Get Recent Badges.

Badge Location

Returns a specific badge class, based on its location URL (encoded).

NB: The location of a badge class is found within the _directory._location field, which is present in the data for each badge returned from the API endpoints /recent and /search. You can therefore combine the location endpoint with those other endpoints if that suits the purpose of your site or application.

Available Request Parameters

The encoded badge class location, appended to the Directory URL.

Expected Request

GET /http%3A%2F%2Fissuersite.com%2Fbadgeclass

Expected Response

JSON-structured object containing requested badge class.

{
  "data": {
      "name": "Badge Name",
      "description": "Badge description.",
      "image": "http://issuersite.com/badge.png",
      "tags": [
        "tag1",
        "tag2",
        ...
      ],
      "issuer": "http://issuersite.com",
      "criteria": "http://issuersite.com/criteria.html",
      "alignment": [
        {
          "name": "Alignment Name",
          "url": "http://alignmentsite.com",
          "description": "Alignment desription."
        }
      ],
      "_directory": {
        "_location": "http://issuersite.com/badgeclass",
        "_valid": true,
        "_timestamp": 1409852679994
      },
      "issuerResolved": {
        "name": "Issuer Name"
      }
    }
}

Response Structure

  • data
    • name
    • description
    • image
    • tags [ ]
    • issuer
    • criteria
    • alignment [ ]
      • name
      • url
      • description
    • _directory
      • _location
      • _valid
      • _timestamp
    • issuerResolved
      • name

Potential Errors

{
  "code": "ResourceNotFound",
  "message": "/http%3A%2F%2Fissuersite.com%2Fbadgeclass does not exist"
}

For more on the /{location} endpoint, see Get a Badge from its Location.

Tags

Returns all tags in the directory, sorted by most popular.

You can use the tag information to carry out search queries.

Available Request Parameters

 Parameter   Type   Description 
 limit   integer   how many results to return (default 10, max 100) 

Parameter not required.

Expected Request

GET /tags
GET /tags?limit=10

cURL Example

curl http://directory.openbadges.org/tags

Expected Response

JSON-structured array of badge tags together with the number of times each tag occurs (for badges currently in the directory).

{
  "data": [
    {
      "tag": "technology",
      "count": 100
    },
    {
      "tag": "science",
      "count": 60
    },
    {
      "tag": "design",
      "count": 40
    },
    ...
  ]
}

Response Structure

  • data
    • tag
    • count

Potential Errors

NONE

For more on the /tags endpoint, including an overview of how you can combine it with the /search endpoint, see Find Badge Tags.

Libraries and Examples

NodeJS: https://github.com/jpcamara/openbadges-directory-client

PHP: https://github.com/Achievery/openbadges-directory-php-client

Example Browser: http://directory.openbadges.org/examples/browser/#/recent