March 2025: HoD API migration

An important update will occur in the History on Demand (HoD) API services that will impact how you call the HoD APIs. These APIs will change how you authenticate, and their endpoints will change from calling HoD APIs from api.weather.com to api.ibm.com.

Upcoming changes

Starting on 31 March 2025, HoD API requests must be authenticated by using a JWT token, and be called from api.ibm.com.

These changes will improve security across the HoD API services.

Action required

Review your integrations and update any HoD API requests to ensure that:
  • Your calls are using a JWT token instead of the old API key.
  • Your calls are changed from api.weather.com to api.ibm.com.

This adjustment will prevent disruptions to your services when the change goes live.

To call the HoD APIs from api.ibm.com, you will need an IBMid, if you do not already have one. An IBMid is required for all users in our organization who need an EIS API key to use api.ibm.com. For more information, refer to Create an IBMid.

You will also need the following IDs, provided to you at the time of the onboarding process:
  • Organization ID: <your-eis-org-id>
  • Tenant ID: <your-eis-tenant-id>
  • EIS API key: <your-eis-api-key>

Application changes

Replace the existing HoD API calls in your application by following these steps:
  1. Authentication:
    Obtain a JWT token by using the EI API key by calling the authentication endpoint. Replace <your-eis-org-id>, <your-eis-tenant-id> and <your-eis-api-key> with your actual values:
    curl -X GET 'https://api.ibm.com/saascore/run/authentication-retrieve/api-key?orgId=<your-eis-org-id>' \
  --header 'x-ibm-client-Id: saascore-<your-eis-tenant-id>' \
  --header 'x-api-key: <your-eis-api-key>'
    For example, the following snippet shows the request and the JWT token response, with some fields masked with asterisks for security purposes:
    curl -X GET 'https://api.ibm.com/saascore/run/authentication-retrieve/api-key?orgId=25b282**-****-****-****-******363625' \
  --header 'x-ibm-client-Id: saascore-737046**-****-****-****-******f71f85' \
  --header 'x-api-key: PHXLuB**********************************VL1mfk'

eyJraWQiOiJVSUhVQjpQUk9EOktFWToyM********************************************************************RaIfhpKEwaWDgGJ02qQ
    Note: The JWT token is valid for 1 hour, so it can be reused for subsequent API calls until the time it expires.
  2. API call:
    Update your application to use the JWT obtained earlier and your tenant ID to run the intended HoD API. Replace <your-eis-tenant-id> and <JWT> with your actual values:
    curl -X GET 'https://api.ibm.com/geospatial/run/v3/wx/hod/r1/direct?geocode=41.10848,-73.72047&startDateTime=2023-06-14T21&endDateTime=2023-06-15T02&products=temperature,evapotranspiration&format=json&units=e&compact=false' \
  --header 'x-ibm-client-id: geospatial-<your-eis-tenant-id>' \
  --header 'Authorization: Bearer <JWT>'

    Note the new API endpoint domain (api.ibm.com instead of api.weather.com) and path (e.g. /geospatial/run/v3/wx/hod/r1/direct instead of /v3/wx/hod/r1/direct). In addition, the old API key request parameter is no longer required as it is replaced by the JWT token in the Authorization header.

    For example, the following snippet shows the request and the response, with some fields masked with asterisks for security purposes:
    curl -X GET 'https://api.ibm.com/geospatial/run/v3/wx/hod/r1/direct?geocode=41.10848,-73.72047&startDateTime=2023-06-14T21&endDateTime=2023-06-15T02&products=temperature,evapotranspiration&format=json&units=e&compact=false' \
  --header 'x-ibm-client-id: geospatial-737046**-****-****-****-******f71f85' \
  --header 'Authorization: Bearer eyJraWQiOiJVSUhVQjpQUk9EOktFWToyM********************************************************************RaIfhpKEwaWDgGJ02qQ'

[{"requestedLatitude":41.10848,"requestedLongitude":-73.72047,"latitude":41.12087912087912,"longitude":-73.74025258526683,"gridpointId":"dr79cvzfrx6qt","validTimeUtc":"2023-06-14T21:00:00+0000","evapotranspiration":0.0,"temperature":68.1},{"requestedLatitude":41.10848,"requestedLongitude":-73.72047,"latitude":41.12087912087912,"longitude":-73.74025258526683,"gridpointId":"dr79cvzfrx6qt","validTimeUtc":"2023-06-14T22:00:00+0000","evapotranspiration":0.0,"temperature":65.9},{"requestedLatitude":41.10848,"requestedLongitude":-73.72047,"latitude":41.12087912087912,"longitude":-73.74025258526683,"gridpointId":"dr79cvzfrx6qt","validTimeUtc":"2023-06-14T23:00:00+0000","evapotranspiration":0.0,"temperature":64.7},{"requestedLatitude":41.10848,"requestedLongitude":-73.72047,"latitude":41.12087912087912,"longitude":-73.74025258526683,"gridpointId":"dr79cvzfrx6qt","validTimeUtc":"2023-06-15T00:00:00+0000","evapotranspiration":0.0,"temperature":62.9},{"requestedLatitude":41.10848,"requestedLongitude":-73.72047,"latitude":41.12087912087912,"longitude":-73.74025258526683,"gridpointId":"dr79cvzfrx6qt","validTimeUtc":"2023-06-15T01:00:00+0000","evapotranspiration":0.0,"temperature":62.0}]
    Note: To ensure satisfactory response time and availability, HoD API calls are limited to 250 per minute. If your use case requires more, contact support.