Skip to main content

Getting Started

The following guide will enable you to get data from MetService's public API, and understand how to integrate with the wider platform.

API Maturity Model Scope​

To help you choose the right integration path, we categorize our APIs into two maturity levels: Core and Classic. See our Maturity Model & Modernization Path for detailed definitions, future roadmaps, and lifecycle information.

Platform Guides Scope

The Platform Guides in this section (covering Limits and Error Handling) apply exclusively to Core APIs. Classic APIs are stable, established services that have their own specific, in-line documentation and guides located within their respective sections in the API Catalog.

For a detailed breakdown of each category and to see which APIs provide the data you need, please visit our API Catalog.

Prerequisites​

  • Basic understanding of REST APIs - Need help? ChatGPT can explain
  • Your favorite HTTP client (cURL, Postman, or your programming language of choice)
  • A MetService API key (see Authentication)

Quick Start Steps​

Get Your API Key​

The first step is to obtain access. Most APIs require manual access, but the Point Forecast API offers a free tier via self-service.

  • Visit the Authentication page to get your key.
  • Your API key will be included in the header of your requests (e.g., x-api-key for Point Forecast, or apikey for other Core APIs).

Choose Your Location​

APIs typically query data by location. There are a variety of ways to choose your location, but coordinates and station IDs are two of the most common. In the Point Forecast API example below, we will use latitude and longitude coordinates (lon=174.784&lat=-37.793).

Choose Your Temporal Parameters​

You can customize the time horizon and frequency of your data. Across our APIs, parameters like time range and time interval are very common.

For the Point Forecast API example below, we query time-series data using a from start date, an interval step size, and a repeat count.

Make Your First Request​

Here's a complete example getting 3-hourly point forecast wave height data for a specific coordinate:

curl -X 'GET' \
  '`https://forecast-v2.metoceanapi.com/point/time?lon=174.7842&lat=-37.7935&variables=wave.height&from=2021-08-29T00:00:00Z&interval=3h&repeat=3'` \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'accept: application/json'

Example Response (Truncated)​

{
  "dimensions": {
    "point": {
      "type": "point",
      "data": [{"lon": 174.7842, "lat": -37.7935}]
    },
    "time": {
      "type": "time",
      "data": ["2021-08-29T00:00:00Z", "2021-08-29T03:00:00Z", "2021-08-29T06:00:00Z"]
    }
  },
  "noDataReasons": {"GOOD": 0, "MASK_LAND": 1},
  "variables": {
    "wave.height": {
      "units": "meter",
      "data": [1.289, 1.344, 1.384]
    }
  }
}

Next Steps​

  1. Explore API Guides

  2. Learn Best Practices

  3. Integration Resources

    • Code Examples & SDKs: We provide generated code samples in popular languages for every endpoint within the API Reference pages.
    • API Reference

Need Help?​