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
    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
    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
    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
    This parameter is used to call a specific function after executing the requests. Alphanumeric values are accepted. E.g.: callback=saverecord
  • page
    This parameter is used for pagination. Only numeric values are accepted. E.g.: page=7

 

Methods

content_type_feed

This method will retrieve all records of the selected content type.

URL

https://www.preventionweb.net/v2/api/v1/content_type_feed/get/output.json?api_key=[API KEY]?page=2&ct=8

Parameter

Field Description Type/Value
ct content type 8 for documents and publications

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",
		"attachments":[{"title":"View full document","url":"http:\/\/www.unisdr.org\/", ...}],
		"pub_year":"2017"}, ...],
	"total":32,
	"total_records":70,
	"total_pages":2,
	"status":200
}

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
}

experts.list

This method will retrieve the list of expert services.

URL

http://www.preventionweb.net/v2/api/v2/experts/get/output.json?type=[TYPE]&api_key=[API KEY]

Types

  • blog - DRR voices blog
  • ask - Ask an expert
  • guest - Guest editorial

Output

{
	"results":[{
		"title":"Drought puts spotlight on Central American climate change woes",
		"link":"http:\/\/www.preventionweb.net\/go\/39164",
		"organizations":[{"org_title":"United Nations Office for Disaster Risk Reduction",
		"org_type":"UN & International Organization"}],
		"meta_desc":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ...<\/p>\n",
		"hazards":"",
		"themes":"",
		"regions":"",
		"countries":"",
		"pub_year":"2014"}, ...],
	"total":23,
	"status":200
}

Result fields

Field Description Type/Value
title title of the document e.g.: Disaster Risk Reduction
link URL reference of the document in PreventionWeb.net e.g.: http://www.preventionweb.net/go/39164
organizations source organization e.g.: [{"org_title":"United Nations Office for Disaster Risk Reduction", "org_type":"UN & International Organization"}]
meta_desc description of the document e.g.: The OSCE implemented a two-year project (2015-2017)
hazards hazards keywords e.g.: Avalanche, Cold Wave
themes themes keywords e.g.: Community-based DRR, Governance
regions regions keywords e.g.: Europe, Asia
countries countries keywords e.g.: Philippines, Switzerland
pub_year publication year of the document e.g.: 2018
total total number of returned results e.g.: 39
total_records total number of records e.g.: 137
total_pages total number of pages e.g.: 7
status status of the request e.g.: 200

 

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.

Themes
List of themes. This can be filtered thru the q parameter.
http://www.preventionweb.net/v2/api/v1/theme/get/output.json


Hazards
List of hazards
http://www.preventionweb.net/v2/api/v1/hazard/get/output.json


Countries
List of countries. This can be filtered thru the q parameter.
http://www.preventionweb.net/v2/api/v1/country/get/output.json


Organization types
List of organization types.
http://www.preventionweb.net/v2/api/v1/org_type/get/output.json


Content types
List of content types.
http://www.preventionweb.net/v2/api/v1/content_type/get/output.json