tambora Vis API Documentation

Introduction

This documentation should help you familiarise yourself with the resources available and how to consume them with HTTP requests. Tambora Vis API is a completely open API. No authentication is required to query and get data. All resources support JSON Schema. The Base URL is the root URL for all of the API, if you ever make a request to tambora Vis API and you get back a 404 NOT FOUND response then check the Base URL first.

The Base URL is:

http://tambora.org/index.php/visapi/

The documentation below assumes you are prepending the Base URL to the endpoints in order to make requests.

Resources

Root

The Root resource provides information on all available resources within the API.

Example request:

http://tambora.org/index.php/visapi/

Event

Returns events per decade optional with date and coding filter, then returns events per year

/event/ -- get all the event resources

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-56486937600000"
                "events": 1
            },
            {
                "unixtime": "-41655168000000"
                "events": 19
            }

Attributes:

unixtime integer -- decade (unixtimestamp).
events integer -- event count per decade.

Optional Parameters:

Filter events by date and/or coding parameter.

date_begin string [y-m-d] -- date begin to filter by.
date_end string [y-m-d] -- date end to filter by.
coding string -- code for temperature (t_high, t_null, t_low), precipitation (p_high, p_null, p_low), flood (f).

http /event?date_begin=1200-1-1&date_end=1250-12-31

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json        
            {
                "unixtime": "-24425107200000"
                "year": 1196
                "events": 2
            }
            {
                "unixtime": "-24298876800000"
                "year": 1200
                "events": 10
            }

Event grid

Returns events within grid, optional with cellsize, date and coding parameter.

/event/grid -- get all the event resources within one degree grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "-167"
                "lat": "68"
                "event_count": 2
            },
            {
                "lon": "-165"
                "lat": "55"
                "event_count": 1
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- event count within grid.

Optional Parameters:

Filter events by cellsize, date and/or coding parameter.

cellsize integer -- grid cell size (0 < cellsize <= 360).
date_begin string [y-m-d] -- date begin to filter by.
date_end string [y-m-d] -- date end to filter by.
coding string -- code for temperature (t_high, t_null, t_low), precipitation (p_high, p_null, p_low), flood (f).

http /event/grid?cellsize=5&date_begin=1400-1-1&date_end=1500-12-31

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json        
            {
                "lon": "-30"
                "lat": "55"
                "event_count": 1
            }
            {
                "lon": "-5"
                "lat": "35"
                "event_count": 2
            }

Event density

Returns event count per defined raster cell. Required parameter: cellsize.

/event/density?cellsize=1 -- get event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "51"
                "count": 27741
                "density": "27741"
                "rank": "1.000"
                "quartile": 1
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
count integer -- event count within grid cell.
density integer -- event count normalized to a 1 by 1 grid cell.
rank integer -- count rank within the result set.
quartile integer -- quartile of the cell ranking within the result set.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Temperature related events

Returns qualified temperature events per decade.

/event/temperature -- get temperature related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "temp_high": null
                "temp_low": 2
                "temp_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
temp_high integer -- high temperature coded event count.
temp_low integer -- low temperature coded event count.
temp_misc integer -- misc temperature coded event count.
quartile integer -- quartile of the item within the result set (ordered by count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nomisc. count, desc.).

No Parameters

Temperature related event density

Returns qualified temperature events per defined grid. Required parameter: cellsize.

/event/temperaturedensity?cellsize=1 -- get temperature related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "temp_high": 9606
                "temp_low": 11656
                "temp_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
                "r_high": "0.45"
                "r_low": "0.55"
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
temp_high integer -- high temperature coded event count.
temp_low integer -- low temperature coded event count.
temp_misc integer -- misc temperature coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).
r_high integer -- hight to low ratio.
r_low integer -- low to high ratio.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Extreme temperature related events

Returns extreme temperature events (very hot/very cold) per decade.

/event/temperaturex -- get temperature related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "temp_high": null
                "temp_low": 2
                "temp_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- overall event count.
temp_high integer -- high temperature (+3) coded event count.
temp_low integer -- low temperature (-3) coded event count.
temp_misc integer -- other temperature coded event count.
quartile integer -- quartile of the item within the result set (ordered by count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nomisc. count, desc.).

Optional Parameters:

Filter events by coding parameter.

coding string -- code for extreme temperature (t_high, t_low)

Extreme temperature related event density

Returns qualified extreme temperature (very hot/very cold) events per defined grid. Required parameter: cellsize.

/event/temperaturexgrid?cellsize=1 -- get temperature related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "temp_high": 9606
                "temp_low": 11656
                "temp_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
temp_high integer -- extremely high temperature (+3) coded event count.
temp_low integer -- extremely low temperature (-3) coded event count.
temp_misc integer -- other temperature coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Optional Parameters:

Filter events by date and/or coding parameter.

date_begin string [y-m-d] -- date begin to filter by.
date_end string [y-m-d] -- date end to filter by.
coding string -- code for extreme temperature (t_high, t_low).

Harvest quantity related events

Returns qualified harvest quantity events per decade.

/event/harvestquantity -- get harvest quantity related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "harvest_quant_high": null
                "harvest_quant_low": 2
                "harvest_quant_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
harvest_quant_high integer -- high harvest quantity coded event count.
harvest_quant_low integer -- low harvest quantity coded event count.
harvest_quant_misc integer -- misc harvest quantity coded event count.
quartile integer -- quartile of the item within the result set (ordered by events, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

No Parameters

Harvest quantity related event density

Returns qualified harvest quantity events per defined grid. Required parameter: cellsize.

/event/harvestquantitydensity?cellsize=1 -- get harvest quantity related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "harvest_quant_high": 9606
                "harvest_quant_low": 11656
                "harvest_quant_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
                "r_high": "0.45"
                "r_low": "0.55"
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
harvest_quant_high integer -- high harvest quantity coded event count.
harvest_quant_low integer -- low harvest quantity coded event count.
harvest_quant_misc integer -- misc harvest quantity coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.)..
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).
r_high integer -- high to low ratio.
r_low integer -- low to high ratio.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Harvest quality related events

Returns qualified harvest quality events per decade.

/event/harvestquality -- get harvest quality related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "harvest_qual_high": null
                "harvest_qual_low": 2
                "harvest_qual_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
harvest_qual_high integer -- high harvest quality coded event count.
harvest_qual_low integer -- low harvest quality coded event count.
harvest_qual_misc integer -- misc harvest quality coded event count.
quartile integer -- quartile of the item within the result set (ordered by events, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

No Parameters

Harvest quality related event density

Returns qualified harvest quality events per defined grid. Required parameter: cellsize.

/event/harvestqualitydensity?cellsize=1 -- get harvest quality related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "harvest_qual_high": 9606
                "harvest_qual_low": 11656
                "harvest_qual_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
                "r_high": "0.45"
                "r_low": "0.55"
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
harvest_qual_high integer -- high harvest quality coded event count.
harvest_qual_low integer -- low harvest quality coded event count.
harvest_qual_misc integer -- misc harvest quality coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).
r_high integer -- high to low ratio.
r_low integer -- low to high ratio.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Short term precipitation related events

Returns qualified short term precipitation events per decade.

/event/precipitationshort -- get short term precipitation related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "precipitation_high": null
                "precipitation_low": 2
                "precipitation_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
precipitation_high integer -- high short term precipitation coded event count.
precipitation_low integer -- low short term precipitation coded event count.
precipitation_misc integer -- misc short term precipitation coded event count.
quartile integer -- quartile of the item within the result set (ordered by events, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

No Parameters

Short term precipitation related event density

Returns qualified short term precipitation events per defined grid. Required parameter: cellsize.

/event/precipitationshortdensity?cellsize=1 -- get short term precipitation related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "precipitation_high": 9606
                "precipitation_low": 11656
                "precipitation_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
                "r_high": "0.45"
                "r_low": "0.55"
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
precipitation_high integer -- high short term precipitation coded event count.
precipitation_low integer -- low short term precipitation coded event count.
precipitation_misc integer -- misc short term precipitation coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).
r_high integer -- high to low ratio.
r_low integer -- low to high ratio.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Dry days related events

Returns dry days events per decade.

/event/drydays -- get dry days related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.

No Parameters

Dry days related event density

Returns dry days events per defined grid. Required parameter: cellsize.

/event/drydaysdensity?cellsize=1 -- get dry days related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 13
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- event count.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Long term precipitation related events

Returns qualified long term precipitation events per decade.

/event/precipitationlong -- get long term precipitation related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "precipitation_high": null
                "precipitation_low": 2
                "precipitation_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
precipitation_high integer -- high long term precipitation coded event count.
precipitation_low integer -- low long term precipitation coded event count.
precipitation_misc integer -- misc long term precipitation coded event count.
quartile integer -- quartile of the item within the result set (ordered by events, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

No Parameters

Long term precipitation related event density

Returns qualified long term precipitation events per defined grid. Required parameter: cellsize.

/event/precipitationlongdensity?cellsize=1 -- get long term precipitation related event count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "event_count": 22698
                "precipitation_high": 9606
                "precipitation_low": 11656
                "precipitation_misc": 1436
                "quartile": 1
                "nonmisc_count": 21262
                "nonmisc_quartile": 1
                "r_high": "0.45"
                "r_low": "0.55"
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
event_count integer -- overall event count.
precipitation_high integer -- high long term precipitation coded event count.
precipitation_low integer -- low long term precipitation coded event count.
precipitation_misc integer -- misc long term precipitation coded event count.
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).
r_high integer -- high to low ratio.
r_low integer -- low to high ratio.

Required Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Wind force related events

Returns qualified wind force events per decade.

/event/windforce -- get wind force related event count

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "unixtime": "-39446265600000"
                "events": 2
                "windforce_high": null
                "windforce_low": 2
                "windforce_misc": null
                "quartile": 4
                "nonmisc_count": 2
                "nonmisc_quartile": 4
            }

Attributes:

unixtime integer -- unixtimestamp.
events integer -- event count.
windforce_high integer -- high wind force coded event count (bft 8 - 12).
windforce_low integer -- low wind force coded event count (bft 4 - 7).
windforce_misc integer -- misc wind force coded event count. (bft 0 - 3)
quartile integer -- quartile of the item within the result set (ordered by event_count, desc.).
nonmisc_count integer -- for convenience: sum of nonmisc. code count.
nonmisc_quartile integer -- quartile of the item within the result set (ordered by nonmisc_count, desc.).

No Parameters

Event locations within grid

Returns event locations within grid. Optional parameter: cellsize.

/location/grid -- get event location count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "location_count": 134
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
location_count integer -- event location count.

Optional Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).

Temperature related event locations within grid

Returns temperature related event locations within grid. Optional parameter: cellsize, date_begin, date_end.

/location/temperature -- get event location count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "10"
                "lat": "50"
                "location_count": 134
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
location_count integer -- event location count.

Optional Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).
date_begin string [y-m-d] -- date begin to filter by.
date_end string [y-m-d] -- date end to filter by.

Flood related event locations within grid

Returns flood related event locations within grid. Optional parameter: cellsize, date_begin, date_end.

/location/floods -- get event location count per defined grid

Example response:

HTTP/1.0 200 OK
            Content-Type: application/json
            {
                "lon": "1"
                "lat": "49"
                "heavy_flood_count": 0
                "heavy_above_avg_flood_count": 0
                "heavy_above_avg_small_flood_count": 0
                "location_count": 1
            }

Attributes:

lon integer -- longitude.
lat integer -- latitude.
heavy_flood_count integer -- heavy flood related event count.
heavy_above_avg_flood_count integer -- heavy to above average flood count.
heavy_above_avg_small_flood_count integer -- heavy to above average small flood related event count.
location_count integer -- event location count.

Optional Parameters:

cellsize integer -- grid cell size (0 < cellsize <= 360).
date_begin string [y-m-d] -- date begin to filter by.
date_end string [y-m-d] -- date end to filter by.