Ramani API End-point Reference

The RAMANI API specification defines an HTTP interface for requesting georeferenced information of from the COPERNICUS and Sentinel data services. While RAMANI supports the most common OGC protocols, notably WMS 1.1.1 as well as WMS 1.3.0 to request Map images, we also provide access to the physical units underlying this data, returned by the API as GeoJSON and other common data-access formats, for backend consumption custom or visualisation.

Request Supported

Operation Description
GetMetadata *) Requests metadata (e.g. date-range, layer details, units, etc.).
GetMap Requests Map-tiles (in png).
GetFeatureInfo *) Retrieves the underlying data, including geometry and attribute values, for a pixel location on a map
GetFeatureInfoEx (Experimental) Retrieves the underlying data, including geometry and attribute values, for a pixel location on a map (also for some experimental datasets).
GetVerticleProfile *) Same as Get Point Info (getFeatureInfo), but along a vertical dimension instead of a single point. Only works on layers that have a vertical dimension (explore the maps we have on offer in our SDL).
GetTimeseriesProfile *) Same as Get Location Info (getFeatureInfo) but varying in time (along a temporal dimension). Only works on layers that have a temporal dimension (explore the maps we have on offer in our SDL).
GetTransect *) Same as Get Location Info (getFeatureInfo), but along a horizontal line (input is LINESTRING with LatLng points).
GetArea *) Same as Get a Horizontal Profile (getTransect), but for an area defined by a LINESTRING, which must contain 3 or more elements to define a polygon.

*): Some request-methods listed above are not supported for Experimental data products.

Required Parameters

request
token

You must provide the API-Key that you get from our client-area. To get it, please register here (if you have not done already).
package The package name of your application.

Get Metadata (GetMetadata)

The GetMetadata request is used to request small pieces of metadata from RAMANI. Many of these are also present in the capabilities document, but GetMetadata provides a more convenient method of accessing such data. GetMetadata always returns data in the JSON format. All GetMetadata requests must provide the parameter ITEM which states the type of metadata requested. ITEM can take the following values:

menu Returns a tree representation of the available WMS layers, with IDs. Takes the optional parameter DATASET to return the same tree for a single dataset
layerDetails Returns a set of details needed to plot a given layer. This includes such data as units, layer bounding box, configured scale range, etc. Takes the parameters LAYERNAME and TIME. The TIME parameter is optional, and if it is specified then the nearest available time is returned as part of the layer’s details.
minmax Calculates the range of values in the given area. Takes the same parameters as a GetMap request.
timesteps Returns the available times for a given day. Takes the parameters LAYERNAME and DAY (yyyy-mm-dd)
animationTimesteps Returns a list of time strings at different temporal resolutions for a given time range. This is used to present to the user different frequencies for the generation of an animation. Takes the parameters LAYERNAME, START, and END 


https://ramani.ujuizi.com/ddl/wms?
    item=layerDetails
    &layerName=simS1seriesTwenteNetherlands/smc
    &time=
    &request=GetMetadata
    &token=
    &package=

return :

{
  "units": "m3 m-3",
  "bbox": [
    "6.124999885447323",
    "52.12499894294888",
    "6.864999868907034",
    "52.614998931996524"
  ],
  "scaleRange": [
    "0.12966593",
    "0.51610005"
  ],
  "numColorBands": 250,
  "supportedStyles": [
    "boxfill"
  ],
  "datesWithData": {
    "2008": {
      "4": [
        23
      ],

      ...

      "10": [
        1,
        6,
        18,
        23
      ]
    },
    "2010": {
      "4": [
        24,
        29
      ],

      ...

      "10": [
        5,
        12,
        19,
        22,
        24,
        29
      ]
    }
  },
  "nearestTimeIso": "2010-11-29T00:00:00.000Z",
  "timeAxisUnits": "ISO8601",
  "moreInfo": "http://ramani.ujuizi.com/thredds/dodsC/Sentinel-1-timeseries-Holland.info",
  "copyright": "http://ramani.ujuizi.com/thredds/esaSentinel1Catalog.html?dataset=simS1seriesTwenteNetherlands",
  "palettes": [
    "seq-YlGnBu",
    "div-BrBG",
    "ncview",

    ...

    "seq-BuPu",
    "seq-Purples"
  ],
  "defaultPalette": "rainbow",
  "logScaling": false
}

Get a Map Layer (getMap)

All of the standard parameters for GetMap are supported on RAMANI. Additional notes on some of these:

FORMAT The supported formats are:
  • image/png
  • image/png;mode=32bit
  • image/gif
  • image/jpeg
  • application/vnd.google-earth.kmz
TIME For gridded data with a discrete time axis this takes a single value. For in-situ data which is spread over a range, it is more useful to provide a time range in the form starttime/endtime. The default value for this parameter is near datetime.
ELEVATION For gridded data with a discrete vertical axis this takes a single value. For in-situ data which is spread over a range, it is more useful to provide an elevation range in the form startelevation/endelevation. This should ideally be used in conjunction with the TARGETELEVATION parameter (see below).
STYLES Available styles can be found from a GetCapabilities-request http://ramani.ujuizi.com/ddl/wms?SERVICE=WMS&REQUEST=GetCapabilities&VERSION=1.3.0&DATASET=[LAYER_ID]&token=[API_KEY], e.g. example Capabilities document. Generally styles are of the form stylename/palettename, and the style name default is always available. 

https://ramani.ujuizi.com/cloud/wms/ramaniddl/tilecache?
                SERVICE=WMS
                &REQUEST=GetMap
                &VERSION=1.1.1
                &LAYERS=ddl.simS1seriesTwenteNetherlands.smc
                &STYLES=boxfill%2Frainbow
                &FORMAT=image%2Fpng
                &TRANSPARENT=true
                &HEIGHT=256
                &WIDTH=256
                &STYLE=boxfill%2Frainbow
                &SRS=EPSG%3A3857
                &ZINDEX=400
                &REUSETILES=true
                &TOKEN=
                &PACKAGE=
                &COLORSCALERANGE=
                &ELEVATION=0
                &EXCEPTIONS=application%2Fvnd.ogc.se_inimage
                &LOGSCALE=false
                &NUMCOLORBANDS=250
                &TIME=2010-11-29T00%3A00%3A00.000Z
                &BBOX=665307.8941941741,6887893.492833804,704443.6526761843,6927029.251315814

Note: For Sentinel-2 Product(s), you can add optional parameter MAXCC with a value between 0-100.
MAXCC = The maximum acceptable percentage of the image covered by clouds ('cloudiness').

Get Location Info (getFeatureInfo)

The GetFeatureInfo request works as-per the standard WMS OCG protocol, with the following notable points:

INFO_FORMAT The supported formats are:
  • text/xml
  • text/plain
  • text/json
  • text/geojson
 

https://ramani.ujuizi.com/ddl/wms?
              TIME=2010-11-29T00%3A00%3A00.000Z
              &token=
              &package=
              &SERVICE=WMS
              &VERSION=1.1.1
              &REQUEST=GetFeatureInfo
              &SRS=EPSG%3A4326
              &BBOX=5.4437255859375%2C52.15624211595189%2C7.547607421875%2C52.58386028042404
              &X=702
              &Y=332
              &INFO_FORMAT=text%2Fjson
              &QUERY_LAYERS=simS1seriesTwenteNetherlands%2Fsmc
              &WIDTH=1532&HEIGHT=510


return :
{

    "type": "FeatureInfoResponse",
    "features": [
        {
            "geometry": {
                "type": "Point",
                "coordinates": [
                    6.4084625244140625,
                    52.305070006527984
                ]
            },
            "properties": {
                "iIndex": 28,
                "jIndex": 31,
                "gridCentreLon": 6.404999879188836,
                "gridCentreLat": 52.304998938925564
            },
            "featureInfo": [
                {
                    "time": "2010-11-29T00:00:00.000Z",
                    "value": 0.36175844
                }
            ]
        }
    ]

}

Get Location Info (getFeatureInfoEx) - Experimental

The GetFeatureInfo Experimental request works as per the standard WMS, with the following notable points:

INFO_FORMAT The supported formats are:
  • text/xml
  • application/json
 

https://ramani.ujuizi.com/maps/getexinfo.php?
                    token=
                    &package=
                    &BBOX=7.136993408203125,44.26388770060487,9.019775390625,44.751609766121646
                    &HEIGHT=498
                    &INFO_FORMAT=application%2Fjson
                    &LAYERS=ddl.GLOBALS2NDVI
                    &QUERY_LAYERS=ddl.GLOBALS2NDVI
                    &REQUEST=GetFeatureInfo
                    &SERVICE=WMS
                    &SRS=EPSG:4326
                    &TIME=2017-09-14
                    &VERSION=1.1.1
                    &WIDTH=1371
                    &X=501
                    &Y=333


return :
{
    "success": true,
    "var": [
        "b04",
        "b08",
        "ndvi"
    ],
    "data": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "id": 2731794,
                "geometry": {
                    "type": "MultiPolygon",
                    "crs": {
                        "type": "name",
                        "properties": {
                            "name": "urn:ogc:def:crs:EPSG::4326"
                        }
                    },
                    "coordinates": [
                        [
                            [
                                [
                                    7.727463259,
                                    45.14673833
                                ],
                                [
                                    9.124153656,
                                    45.153760768
                                ],
                                [
                                    9.122062002,
                                    44.165310291
                                ],
                                [
                                    7.74889526,
                                    44.158524447
                                ],
                                [
                                    7.727463259,
                                    45.14673833
                                ]
                            ]
                        ]
                    ]
                },
                "properties": {
                    "id": "MSI/L1C/2017/08/30/S2B_MSIL1C_20170830T102019_N0205_R065_T32TMQ_20170830T102531.SAFE/GRANULE/L1C_T32TMQ_A002522_20170830T102531/IMG_DATA/T32TMQ_20170830T102019_",
                    "date": "2017-08-30",
                    "time": "10:25:31",
                    "crs": "EPSG:32632",
                    "mbr": "399960,4890240 509760,5000040",
                    "cloudCoverPercentage": 10.7,
                    "b04": "0.4666000009",
                    "b08": "0.5414000154",
                    "ndvi": "0.0742063597"
                }
            }
        ]
    }

}

Get a Vertical Profile (getVerticalProfile)

This request retrieves either a vertical profile or a vertical slice in a 3D dataset (require data with 'depth' or 'height'). The URL parameters are identical to those of a GetFeatureInfo request. The ELEVATION parameter should specify a range of elevations in the form startelevation/endelevation, and the supported formats are:

  • image/png
  • image/svg
  • text/xml
  • text/json
  • text/gejson

https://ramani.ujuizi.com/ddl/wms?
              token=
              &package=
              &REQUEST=GetVerticalProfile
              &LAYER=simS5seriesNO2Europe/no2_conc
              &CRS=CRS:84
              &TIME=2017-08-15T00:00:00.000Z
              &POINT=8.825%2044.400
              &FORMAT=text/json

return :

{

    "type": "Vertical Profile",
    "verticalprofile": {
        "dataset": "Sentinel-5: Time-series Nitrogen Dioxide Forecast (Europe)",
        "time": "2017-08-15T00:00:00.000Z",
        "point": {
            "type": "Point",
            "coordinates": [
                "8.825E",
                "44.4N"
            ]
        },
        "variable": [
            {
                "name": "Nitrogen Dioxide (NO2)",
                "units": "µg/m3"
            },
            {
                "name": "height",
                "units": "m"
            }
        ],
        "data": [
            {
                "height": 0,
                "value": 13.155502
            },
            {
                "height": 50,
                "value": 13.704017
            },
            {
                "height": 250,
                "value": 1.6702627
            },
            {
                "height": 500,
                "value": 1.0529836
            },
            {
                "height": 1000,
                "value": 0.36291724
            },
            {
                "height": 2000,
                "value": 0.11737702
            },
            {
                "height": 3000,
                "value": 0.13521382
            },
            {
                "height": 5000,
                "value": 0.029063959
            }
        ]
    }

}

Get a Time-series Profile (getTimeseriesProfile)

This produces either a timeseries graph. The URL parameters are identical to those of a GetFeatureInfo request. The TIME parameter should specify a range of times in the form starttime/endtime, and the supported formats are:

  • image/png
  • image/svg
  • text/xml
  • text/json
  • text/gejson

https://ramani.ujuizi.com/ddl/wms?
              token=
              &package=
              &TIME=2010-11-05T00:00:00.000Z/2010-11-29T00:00:00.000Z
              &SERVICE=WMS
              &VERSION=1.1.1
              &REQUEST=GetFeatureInfo
              &SRS=EPSG%3A4326
              &BBOX=5.5535888671875,52.0102459910103,7.436370849609375,52.72797579969741
              &X=660
              &Y=447
              &INFO_FORMAT=text/json
              &QUERY_LAYERS=simS1seriesTwenteNetherlands/smc
              &WIDTH=1371
              &HEIGHT=856

return :
{
  "type": "FeatureInfoResponse",
  "features": [
    {
      "geometry": {
        "type": "Point",
        "coordinates": [
          6.4606475830078125,
          52.35276074200175
        ]
      },
      "properties": {
        "iIndex": 34,
        "jIndex": 26,
        "gridCentreLon": 6.464999877847731,
        "gridCentreLat": 52.35499893780798
      },
      "featureInfo": [
        {
          "time": "2010-11-05T00:00:00.000Z",
          "value": 0.57088435
        },
        {
          "time": "2010-11-12T00:00:00.000Z",
          "value": 0.5365712
        },
        {
          "time": "2010-11-19T00:00:00.000Z",
          "value": 0.60175943
        },
        {
          "time": "2010-11-22T00:00:00.000Z",
          "value": 0.6289388
        },
        {
          "time": "2010-11-24T00:00:00.000Z",
          "value": 0.48772228
        },
        {
          "time": "2010-11-29T00:00:00.000Z",
          "value": 0.43444437
        }
      ]
    }
  ]
}

Get a Horizontal Profile (getTransect)

This produces a graph of data values along an arbitrary path. Additionally if there is vertical information present in the dataset, it will produce a vertical section along the same path. It takes the same URL parameters as a GetMap request with the addition of a parameter LINESTRING of the format x1 y1,x2 y2,x3 y3... which defines the control points of the graph. 


https://ramani.ujuizi.com/ddl/wms?
              token=
              &package=
              &REQUEST=GetTransect
              &LAYER=simS1seriesTwenteNetherlands/smc
              &CRS=EPSG:4326
              &TIME=2010-11-29T00:00:00.000Z
              &LINESTRING=6.414642333984374%2052.36218321674427,6.598663330078125%2052.39990521956092,
              &FORMAT=text/json
              &VERSION=1.1.1

return :

{
  "type": "GetTransectResponse",
  "transect": {
    "crs": "EPSG:4326",
    "linestring": "6.414642333984374 52.36218321674427,6.598663330078125 52.39990521956092,",
    "dataset": "Sentinel-1: Soil Moisture (Twente-area, The Netherlands)",
    "variable": "Top-soil layer moisture ",
    "units": "m3 m-3",
    "transectData": [
      {
        "time": "2010-11-29T00:00:00.000Z",
        "data": [
          {
            "location": "6.414642333984374 52.36218321674427",
            "value": 0.34283134
          },
          {
            "location": "6.415011113535664 52.36225881194029",
            "value": 0.34283134
          },

              ...

          {
            "location": "6.598294550526835 52.3998296243649",
            "value": 0.4383808
          },
          {
            "location": "6.598663330078125 52.39990521956092",
            "value": 0.4383808
          }
        ]
      }
    ]
  }
}

Get a Area Profile (getArea)

supported output are:

  • aggregate
  • histogram

https://ramani.ujuizi.com/ddl/wms?
                token=
                &package=
                &return=aggregate
                &REQUEST=GetArea
                &LAYER=simS1seriesTwenteNetherlands/smc
                &CRS=EPSG:4326
                &TIME=2010-11-29T00:00:00.000Z
                &LINESTRING=6.25396728515625%2052.382305628707854,6.372899355829467%2052.424196211696774,6.257838787287611%2052.30345857599569,6.491831426502683%2052.466047027219425,6.393805138437476%2052.299363948428585,6.589530531912802%2052.42845437658418,6.525781919719913%2052.2761403394828,6.680521207874537%2052.365691290287685,6.638463891157568%2052.309025707071214,6.638463891157568%2052.309025707071214,
                &FORMAT=text/json
                &VERSION=1.1.1

return :

{
  "type": "GetAreaResponse",
  "area": {
    "crs": "EPSG:4326",
    "linestring": "6.25396728515625 52.382305628707854,6.372899355829467 52.424196211696774,6.257838787287611 52.30345857599569,6.491831426502683 52.466047027219425,6.393805138437476 52.299363948428585,6.589530531912802 52.42845437658418,6.525781919719913 52.2761403394828,6.680521207874537 52.365691290287685,6.638463891157568 52.309025707071214,6.638463891157568 52.309025707071214,",
    "dataset": "Sentinel-1: Soil Moisture (Twente-area, The Netherlands)",
    "variable": "Top-soil layer moisture ",
    "units": "m3 m-3",
    "aggregate": {
      "mean": 0.35117275011539456,
      "stdv": 0.043417971492579664,
      "skew": 0.0178409262404332,
      "kurt": -0.23488043040572792,
      "min": 0.2409188449382782,
      "max": 0.4759962856769562,
      "perc": 0.3519315719604492,
      "median": 0.3519315719604492
    }
  }
}

Note: Same as Get a Horizontal Profile (getTransect), but for an area defined by a LINESTRING, which must consist of 3 or more elements to define a polygon.