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