Documentation

 

API Documentation

Introduction

The main purpose of the PreventionWeb.net API is to share raw meta data from the DRR knowledge base platform for data syndication to other platforms. An API operation requires an API key, see more details below. The current supported outputs are JSON and PHP serialized text.

 

Versions

The current version is version 1, abbreviated as v1.

 

Requests

The API is read-only. It is called using an HTTP GET request.

Scheme: "http://"
Host: "www.preventionweb.net"
Path: "/v2/api/v1/"
Method: e.g.: "theme"
Request: "get"
Output: "output.json" or "output.php"
Parameters (see available options below): e.g.: "?limit=50"

URL format

https://www.preventionweb.net/v2/api/v1/[METHOD NAME]/[REQUEST TYPE:get]/output.[OUTPUT:json|php]?api_key=[API KEY]&limit=[INTEGER:50 default/maximum value, optional]

URL example

https://www.preventionweb.net/v2/api/v1/publications_europe/get/output.json?api_key=[API KEY]

https://www.preventionweb.net/v2/api/v1/theme/get/output.json

Output format

{
  "results":[{record1}, {record2}, ...],
  "total":[INTEGET:143],
  "total_pages":11,
  "status":200
}

Output example

{
  "results":[{"id":41,"name":"Advocacy & Media"},{"id":31,"name":"Capacity Development"}, ...],
  "total":32,
  "status":200
}

 

Parameters

The following are parameters used in this API. Parameters are used to filter queries. Please note that some parameters are required in a specific request but are not in other requests.

  • api_key
    The api_key is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly. This API key is assigned to you by PreventionWeb. To request for an API key, please contact PreventionWeb https://www.preventionweb.net/english/contact/.
  • sortby (optional)
    To sort the results according to field name, use the sortby parameter. The API will accept alphanumeric values. E.g.: sortby=ent_title
    Available fields that can be sorted by:
    1. ent_title - title of the publication
    2. pub_year - publication year
    3. ent_datepublished (default) - publication date on PreventionWeb
  • sortorder (optional)
    This is used to arrange the sorting order of results, either in ascending or in descending (default) order. The API will only accept "asc" or "desc" value (not case sensitive). E.g.: sortorder=desc
  • limit (optional)
    This parameter will limit the number of results to return. The default/maximum value is 50. The API will only accept numeric values. E.g.: limit=25
  • callback (optional)
    This parameter is used to call a specific function after executing the requests. Alphanumeric values are accepted. E.g.: callback=saverecord
  • page (optional)
    This parameter is used for pagination. Only numeric values are accepted. E.g.: page=7

 

Methods

publications_europe.list

This method will retrieve all documents and publications records tagged europe region or country under europe.

URL

https://www.preventionweb.net/v2/api/v1/publications_europe/get/output.json?api_key=[API KEY]

Output

{
	"results":[{
		"title":"Disaster risk reduction and security in the OSCE area: Project highlights",
		"link":"http:\/\/www.preventionweb.net\/go\/55067",
		"organizations":[{"org_title":"Organisation for Security and Cooperation in Europe","org_type":"Regional Intergovernmental Organization"}],
		"meta_desc":"The OSCE implemented a two-year project (2015-2017) \u201cDisaster Risk Reduction and Security in the OSCE Area\u201d in South-Eastern Europe (Albania, Bosnia and Herzegovina, Montenegro and Serbia) and Central Asia (Tajikistan, Kyrgyzstan), which aimed to improve disaster risk governance in municipalities and communities by providing assistance in development of local DRR plans, as well as increase public participation in preparation of plans and strengthen transboundary cooperation. \r\n\r\nThe project leaflets showcase project experiences and achievements in local municipalities and communities in the project area.",
		"hazards":"",
		"themes":"Community-based DRR, Governance",
		"regions":"",
		"countries":"Albania, Bosnia and Herzegovina, Kyrgyzstan, Montenegro, Serbia, Tajikistan",
		"pub_year":"2017"}, ...],
	"total":32,
	"total_records":70,
	"total_pages":2,
	"status":200
}

Result fields

  • title: title of the document
  • link: URL reference of the document in PreventionWeb.net
  • organizations: source organization
  • meta_desc: description of the document
  • hazards: hazards keywords
  • themes: themes keywords
  • regions: regions keywords
  • countries: countries keywords
  • pub_year: publication year of the document
  • total: total number of returned results
  • total_records: total number of records
  • total_pages: total number of pages
  • status: status of the request

 

Controlled Vocabularies

In this section we take a look at the meaning and purpose of Controlled Vocabularies in the context of PreventionWeb.

What is a controlled vocabulary?

A controlled vocabulary is a list of carefully selected disaster reduction related words and phrases that are used on PreventionWeb to tag pieces of content, making it easier to find that when searching or browsing.

Why the need for a controlled vocabulary?

The biggest advantage to having a controlled vocabulary is that once we have established a definition for a term, the relevant information under that term can be grouped together in one place. In addition, any synonyms for the term are grouped under that term and so searches using synonyms will return the same result as searches using the main term.

For example – in a controlled vocabulary that includes the word ‘car’, there could be a subset that includes ‘automobile’, ‘vehicle’ and ‘station wagon’. A search using the term ‘automobile’ will return results for ‘car’ and so - ‘vehicle’ and ‘station wagon’.

PreventionWeb uses the following controlled vocabularies:

  • Regions & Countries
  • Themes & Issues
  • Hazards
  • Organization Types

List

The following controlled vocabularies are available without the need of an API key. The internal meta data ID can be use for cross platform content mapping.