We’re taking the first steps towards an API to enable programmatic access to the RSR data. The current set of resources only comprise a part of the full data set we plan to publish, but should be sufficient to populate a simple map with project and organisation information for example.

When using the Akvo RSR API, please respect our API Code of Conduct: http://www.akvo.org/web/akvo-rsr-api-code-of-conduct

The API is REST-based but currently read-only and lives under

http://www.akvo.org/api/v1/

For instance to get a list of project locations you visit http://www.akvo.org/api/v1/project_location/?format=json

Doing that will return a JSON object (shortened and formatted for readability):

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/project_location/?offset=20&limit=20&format=json",
        "offset": 0,
        "previous": null,
        "total_count": 640
    },
    "objects": [{
        "address_1": "",
        "address_2": "",
        "city": "Kake II",
        "country": "/api/v1/country/8/",
        "id": "1",
        "latitude": 4.630153,
        "longitude": 9.363441,
        "postcode": "",
        "primary": true,
        "project": "/api/v1/project/578/",
        "resource_uri": "/api/v1/project_location/1/",
        "state": ""
    }, {
        "address_1": "",
        "address_2": "",
        "city": "",
        "country": "/api/v1/country/81/",
        "id": "2",
        "latitude": 9.30769,
        "longitude": 2.315834,
        "postcode": "",
        "primary": true,
        "project": "/api/v1/project/577/",
        "resource_uri": "/api/v1/project_location/2/",
        "state": ""
    },
    …
]
}

The default data format is JSON, but you’ll need to add ?format=json when playing with the API in a browser. (A nice syntax high-lighting plugin for Chrome is Sight) When accessing it programmatically it should only be needed if you want XML or JSONP, like http://www.akvo.org/api/v1/project_location/?format=xml

The data returned is a “meta” object with information about the data and a number of data objects in the “objects” list. “meta” holds information about the maximum number of objects returned in “limit” and the total number of objects in “total_count”, in the example here there are 640 project_location objects. The default limit is 20 so if there are more than 20 objects you will get the first 20. This can be changed by adding to the URL so http://www.akvo.org/api/v1/project_location/?format=json&limit=50 would return the first 50 project locations and http://www.akvo.org/api/v1/project_location/?format=json&limit=0 returns all of them.

There may also be information about where to get more objects from the resource. If there are more objects than the value of “limit”, the “next” and “previous” fields hold information about the paths to the corresponding groups of objects. So to access the next batch of 20 project locations you would call http://www.akvo.org/api/v1/project_location/?offset=20&limit=20&format=json

The data of each object holds one meta data key, "resource_uri", which is the path to that particular object when accessed via the API.

Each resource object holds a number of data fields. To find more information about the field types a resource is made up of you can add schema/ to the root URL for the resource so in the case of project location it would be http://www.akvo.org/api/v1/project_location/schema/?format=json

Most of the field types should be self explanatory but the fields that are of “type”: “related” are worth discussing. Each resource represents a table in the database. However database fields that represent foreign keys do not return all the related data but rather the path to that data as it is represented in the API. In the example above you see that there are two fields that are made up this way, “country” and “project”. In the example above we see “country”: “/api/v1/country/8/” in the first project location, so to get the country information we visit http://www.akvo.org/api/v1/country/8/?format=json

The schema also “filtering” object that holds filtering options for the resource. In the schema example above we see that can filter on the project “id”, so to get all project locations for the project with “id”: 2 we would visit http://www.akvo.org/api/v1/project_location/?format=json&project=2

Each resource is accessible in similar ways by requesting URLs with paths constructed in similar ways. Examples of ways to access the project location resource:

• http://www.akvo.org/api/v1/project_location/?format=json Get the first 20 project locations

• http://www.akvo.org/api/v1/project_location/1/?format=json One project location object, with “id” = 1

• http://www.akvo.org/api/v1/project_location/schema/?format=json The schema for the resource

• http://www.akvo.org/api/v1/project_location/set/1;2;4?format=json A set of objects identified by “id”

The root URL of the API, http://www.akvo.org/api/v1/?format=json, returns a list of all resources currently available. Given this information we can construct URLs for all resources in similar ways.

http://www.akvo.org/api/v1/?format=json returns the following:

{
    "category": {
        "list_endpoint": "/api/v1/category/",
        "schema": "/api/v1/category/schema/"
    },
    "country": {
        "list_endpoint": "/api/v1/country/",
        "schema": "/api/v1/country/schema/"
    },
    "link": {
        "list_endpoint": "/api/v1/link/",
        "schema": "/api/v1/link/schema/"
    },
    "organisation": {
        "list_endpoint": "/api/v1/organisation/",
        "schema": "/api/v1/organisation/schema/"
    },
    "organisation_location": {
        "list_endpoint": "/api/v1/organisation_location/",
        "schema": "/api/v1/organisation_location/schema/"
    },
    "partnership": {
        "list_endpoint": "/api/v1/partnership/",
        "schema": "/api/v1/partnership/schema/"
    },
    "project": {
        "list_endpoint": "/api/v1/project/",
        "schema": "/api/v1/project/schema/"
    },
    "project_location": {
        "list_endpoint": "/api/v1/project_location/",
        "schema": "/api/v1/project_location/schema/"
    }
}

URLs to all resources are created by using the pattern

http://www.akvo.org/(list_endpoint)[optional_path_info][optional_query_info]

• (list_endpoint) is the value of one of the “list_endpoint” fields in the root URL above
• [optional_path_info] can be on the form
  • <id>/
  • set/<id1;id2...>/
  • schema/
  • or nothing at all
• [optional_query_info] is the query string. Available identifiers are
  • format=json | jsonp | xml
  • limit=<max number of objects returned, 0 returns all objects>
  • offset=<order of the first object returned>
  • <object to filter on>=<id>