Skip to content

Instantly share code, notes, and snippets.

@tnwei

tnwei/api-docs.md

Created March 8, 2022 13:55
Show Gist options
  • Save tnwei/96c657a35ad2c8af72aea8773b500106 to your computer and use it in GitHub Desktop.
Save tnwei/96c657a35ad2c8af72aea8773b500106 to your computer and use it in GitHub Desktop.
Download ZIP
MetMalaysia API docs - accessed Jan 2, 2022 Sun
Raw
api-docs.md

Mirrored from https://api.met.gov.my/dashboard/docs, accessed Jan 2, 2022 Sun

Getting Started

Malaysian Meteorological Department API is a web service which provides methods for accesing specific resources at canonical URL. We do not support any specific programming language or tools and we expect users already have the necessary understanding of the underlying technology, namely HTTP and JSON. All examples given in this documentation will assume a working knowledge of HTTP and JSON.

Base URL

https://api.met.gov.my/v2.1/

Note: The use of base URL https://api.met.gov.my/v2/ is deprecated.

Data Interchange Format

The supported data interchange format is JSON.

Authentication

Every request must include an authentication token. The authentication token key must be included in the Authorization HTTP header. The key must be prefixed by the string literal “METToken”, followed by a whitespace separating the two strings. For example:

Authorization: METToken d2b812a96ec54568730a319d1d417fb6f85f41a3

Unauthenticated responses that are denied permission will result in HTTP 401 Unauthorized.

Throttling

Every authenticated requests are subjected to throttling.

Rate Description
Burst rate Maximum burst requests is 10 per minute.
Sustained rate Maximum sustained requests is 2,000 per day.

Endpoints

Valid endpoints are:

Endpoint Description
/locations A location is geopolitical entity.
/data A datum is a pre-calculated or observed value with any ancillary attributes at a specific place and time.
/datatypes A data type describes a datum.

Request & Response

Below is an example of a basic HTTP request:

GET /v2.1/<endpoint> HTTP/1.1
User-Agent: <user agent>
Host: api.met.gov.my
Accept: */*
Authorization: METToken d2b812a96ec54568730a319d1d417fb6f85f41a3

Below is an example of a typical basic HTTP response:

HTTP/1.1 200 OK
Date: Mon, 02 Jan 2017 01:21:21 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: max-age=600
ETag: "8078add66f5de3462fb572426f235ea5660c1a7513d935c2cbe65026649b5fb8"
Allow: GET, OPTIONS
X-Frame-Options: SAMEORIGIN
X-Frame-Option: SAMEORIGIN

A client is encouraged to take advantage of ETag and Cache-Control HTTP headers for subsequent request to the same resource.

Data Available

There are 3 types of data available:

  • General (weather) Forecast
  • Marine Forecast
  • Warnings

By default, upon registration you only have access to general forecast, marine forecast & warnings.

General Forecast

In order to query weather forecast data, you need to request from /data endpoint. Most of the time you would want a location that falls under the category TOWN or TOURISTDEST (tourist destination). See Locations for further information.

Five (5) query parameters are required. There is one (1) optional parameter to select language:

Query Parameter Value
datasetid FORECAST
datacategoryid GENERAL
locationid See Locations. In order to fetch data for all locations put the value ALL_LOCATIONS.
start_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be today’s date or greater.
end_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be equal or greater than start_date.
lang en for English or ms for Bahasa Melayu. If this parameter is not specified, the default is English.

For example, to query weather forecast data for Putrajaya which has locationid of LOCATION:237, you will make a call like below:

https://api.met.gov.my/v2.1/data?datasetid=FORECAST&datacategoryid=GENERAL&locationid=LOCATION:237&start_date=2022-01-02&end_date=2022-01-02

Below is an example of response data:

{
    "metadata": {
        "resultset": {
            "count":6,
            "offset":0,
            "limit":50,
            "locationid":"LOCATION:237",
            "datasetid":"FORECAST",
            "datacategoryid":"GENERAL"
        }
    },
    "results": [
        {
            "locationid":"LOCATION:237",
            "locationname":"PUTRAJAYA",
            "locationrootid":"LOCATION:12",
            "locationrootname":"PUTRAJAYA",
            "date":"2022-01-02T00:00:00+08:00",
            "datatype":"FMAXT",
            "value":34,
            "latitude":2.91667,
            "longitude":101.7,
            "attributes": {
                "unit":"Celcius",
                "ref":null,
                "valid_from":null,
                "valid_to":null
            }
        },
        ...
    ]
}

Response data consist of two parts: metadata and results. Metadata are data which describes about the query and data. Results on the other hand are a list of data in response to the request. Most of the attributes in the response are self-explanatory, therefore only relevant attributes will be described.

Important metadata attributes for general forecast:

Atrribute Description
count Total number of records in results.

Important results attributes for general forecast:

| Atrribute | Description| datatype | Type of data. See Data Types. value | The actual value of the result. Can be a string, integer or float. attributes | Further information on the value, if any.

Marine Forecast

In order to query marine forecast data, you need to request from /data endpoint. You need a location that falls under the category WATER. See Locations for further information.

Five (5) query parameters are required. There is one (1) optional parameter to select language:

Query Parameter Value
datasetid FORECAST
datacategoryid GENERAL
locationid See Locations.
start_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be today’s date or greater.
end_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be equal or greater than start_date.
lang en for English or ms for Bahasa Melayu. If this parameter is not specified, the default is English.

For example, to query weather forecast data for Terengganu Waters which has locationid of LOCATION:501, you will make a call like below:

https://api.met.gov.my/v2.1/data?datasetid=FORECAST&datacategoryid=MARINE&locationid=LOCATION:501&start_date=2022-01-02&end_date=2022-01-02

Below is an example of response data:

{
    "metadata": {
        "resultset": {
            "count": 7,
            "offset": 0,
            "limit": 50,
            "locationid": "LOCATION:501",
            "datasetid": "FORECAST",
            "datacategoryid": "MARINE"
        }
    },
    "results": [
        {
            "locationid": "LOCATION:501",
            "locationname": "TERENGGANU",
            "date": "2021-02-09T00:00:00+08:00",
            "datatype": "FMWS",
            "value": "20-30",
            "latitude": null,
            "longitude": null,
            "attributes": {
                "unit": "km/h",
                "ref": null,
                "valid_from": null,
                "valid_to": null
            }
        },
        ...
    ]
}

Response data consist of two parts: metadata and results. Metadata are data which describes about the query and data. Results on the other hand are a list of data in response to the request. Most of the attributes in the response are self-explanatory, therefore only relevant attributes will be described.

Important metadata attributes for marine forecast:

Atrribute Description
count Total number of records in results.

Important results attributes for marine forecast:

Atrribute Description
datatype Type of data. See Data Types.
value The actual value of the result. Can be a string, integer or float.
attributes Further information on the value, if any.

Warnings

There five (5) types of warnings available namely earthquake/tsunami; strong wind & rough seas; thunderstorm; continuous heavy rain; and tropical cyclone. In order to query warnings, you need to request from /data endpoint.

Four (4) query parameters are required:

Query Parameter Value
datasetid WARNING
datacategoryid QUAKETSUNAMI (earthquake/tsunami), WINDSEA (strong wind & rough sea), THUNDERSTORM (thunderstorm), RAIN (continuous heavy rain), CYCLONE (tropical cyclone)
start_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be today’s date or greater.
end_date Date in ISO8601 format (YYYY-MM-DD) e.g. 2022-01-02. The value must be equal or greater than start_date.

Note that start_date and end_date are not a range of warnings published dates. Instead these values represent a range of date which warnings may be valid (not expired or retracted). For example, to query warning for strong wind & rough seas, you will make a call like below:

https://api.met.gov.my/v2.1/data?datasetid=WARNING&datacategoryid=WINDSEA2&start_date=2022-01-02&end_date=2022-01-02

Below is an example of response data:

{
    "metadata": {
        "resultset": {
            "count": 1,
            "offset": 0,
            "limit": 50,
            "datasetid": "WARNING",
            "datacategoryid": "QUAKETSUNAMI"
        }
    },
    "results": [
        {
            "date": "2022-01-02T15:37:11.481920+08:00",
            "datatype": "QUAKETSUNAMI",
            "value": {
                "heading": {
                    "en": "Moderate Earthquake in Banda Sea",
                    "ms": "Gempa Bumi Sederhana di Laut Banda"
                },
                "text": {
                    "en": {
                        "earthquake": "A moderate earthquake of magnitude 5.2 on the Richter ...",
                        "tsunami": "No tsunami threat to Malaysia."
                    },
                    "ms": {
                        "earthquake": "Gempa bumi sederhana bermagnitud 5.2 pada skala Richter ...",
                        "tsunami": "Tiada ancaman tsunami kepada Malaysia."
                    }
                }
            },
            "latitude": null,
            "longitude": null,
            "attributes": {
                "title": {
                    "en": "Earthquake information",
                    "ms": "Maklumat Gempa Bumi"
                },
                "ref": null,
                "timestamp": "2022-01-02T15:24:00+08:00",
                "valid_from": "2022-01-02T15:24:00+08:00",
                "valid_to": "2022-01-02T15:24:00+08:00"
            }
        }
    ]
}

Response data consist of two parts: metadata and results. Metadata are data which describes about the query and data. Results on the other hand are a list of data in response to the request. Most of the attributes in the response are self-explanatory, therefore only relevant attributes will be described.

Important metadata attributes for warning:

Atrribute Description
count Total number of records in results.

Important results attributes for warning:

Atrribute Description
date Date & time published at the API server.
datatype Type of data. See Data Types.
value JSON with heading and text parts. Further information on the value.
attributes valid_from: Start valid period timestamp, valid_to: End valid period timestamp

Locations

There are 5 location categories:

  • STATE (for general forecast)
  • DISTRICT (for general forecast)
  • TOWN (for general forecast)
  • TOURISTDEST (for general forecast)
  • WATERS (for marine forecast)

You can get a list of locations for each category by calling the /locations endpoint using HTTP GET method:

https://api.met.gov.my/v2.1/locations?locationcategoryid=<location category>

For example:

https://api.met.gov.my/v2.1/locations?locationcategoryid=TOWN

Note that you will need a location ID in order to query a set of data.

This resource will only produced a maximum of 50 records in the result. There are times where the total records are more than 50. In such case you may use offset parameter in your HTTP GET query. The offset parameter is a positive integer value and always starts with 0. For example to get the next 50 records:

https://api.met.gov.my/v2.1/locations?locationcategoryid=TOWN&offset=50

Data Types

You can get a list of data types by calling the /datatypes endpoint using HTTP GET method:

https://api.met.gov.my/v2.1/datatypes

From the response, within the results, the id attribute represents the data type. name will provide a brief description about the data type.

Satellite & Radar Images

Latest satellite image:

https://api.met.gov.my/static/images/satelit-latest.gif

Latest current radar image:

https://api.met.gov.my/static/images/radar-latest.gif

Latest forecast radar image:

https://api.met.gov.my/static/images/swirl-latest.gif
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment