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)

Required Request Headers​

All HTTP requests sent to MetService Public APIs must include the following headers:

HeaderRequiredExampleDescription
AuthorizationMandatory (Core)Authorization: Bearer YOUR_API_KEYYour assigned MetService API key. Core APIs use Authorization: Bearer ..., while the Point Forecast API uses x-api-key (see Authentication).
User-AgentMandatoryUser-Agent: MyApp/1.0Identifies your client application. Requests missing a User-Agent header will be rejected with a 403 Forbidden response.
acceptRecommendedaccept: application/jsonSpecifies the expected response content type.
Automated HTTP Clients & Cloudflare Workers

While tools like cURL and Postman inject a default User-Agent header automatically, custom programmatic clients (such as Cloudflare Workers, Node.js fetch, or Python scripts) may omit it by default. Always verify that your application explicitly configures a non-empty User-Agent header.

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 (for example Authorization: Bearer YOUR_API_KEY for Core APIs, or x-api-key for the Point Forecast API).

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 'User-Agent: MyApp/1.0' \
  -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?​