EIS 2022 Announcement - B2B API Enhancements

For Historical Data for Analytical Tools (HDAT r2) API users, there are some new improvements. Some of the updates are technical in nature and drive towards better performance. However, the following aspects of the API and data ingest processes have been improved:

• • the API will query existing global hourly data as it arrives, rather than relying upon the old pre-calculation and static storage of response data, which was only updated every 24 hrs
  • the min/max/avg response values will be calculated at the time of the request
  • the implementation will employ TWC's Location Service
  • the new ingest process, completely reimagined and implemented in IBM Cloud, removes the geographic coverage limitations the old mechanism had

These changes make possible some exciting new characteristics:

• • Global Land point coverage: Any point in the globe is queryable, as long as TWC's Location Service has time zone information for it. Generally, these are points not exceeding 5km distance from shorelines on major water bodies.
  • Global Postal Key support: The previous static list of ~70,000 postal keys is no longer applicable. It has been replaced by dynamic interaction with TWC Location Service functionality, which means any postalKey known to Location Service is queryable in HDAT
  • Queries reflect the most current data available: Because the data arrives hourly and is now immediately available to the API, and because we integrate TWC Location Service:
    • dynamic time zone determination is available, enabling on-the-fly, accurate calculation of local daypart values
    • the lag time of data availability has been reduced from 24 hours to approximately 2 hours
    • each "weather product daypart" (e.g. Temperature/Morning) will be calculated and available as soon as all of its data is present

Should you have any questions or concerns, please email twcapi@us.ibm.com and include the subject line “HDAT r2 updates” so we can swiftly address them.

For History on Demand - Direct (HoD Direct) API users, new improvements available immediately:

Since its inception, HoD Direct has only served weather products from the Gridded Currents on Demand (gCOD) dataset. These are the 30+ fields you are accustomed to seeing in the response. Two new weather products have been added from the AgE dataset: Reference Evapotranspiration (referred to as ET0) and Global Horizontal Irradiance (GHI).

In the past, HoD Direct returned all the weather products available in the gCOD dataset. With the addition of the new dataset, we thought it was time to add the ability to choose exactly what you want returned. The new products request parameter can be followed by “all” or a series of comma-delimited products. So if you only want temperature, dewpoint, and GHI, you specify ". . . /direct?products=temperature,dewpoint,globalHorizontalIrradiance" and your response will only contain that data.

• Special Considerations regarding explicit product specification:
  • For backward compatibility, the omission of the products request parameter will result in a response containing only the gCOD dataset products (same as today).
  • If you specify products=all, the response will contain all products from both datasets.
  • The names of the products themselves are case-insensitive.
  • The API accurately represents the collection timestamp of the data.
    • gCOD data is collected at :20 minutes after the hour, hence you may have noted the minutes in the field: "validTimeUtc": "2021-07-05T14:20:00+0000".
    • However, in the AgE dataset, the minutes are :00.
    • Therefore, if your response contains only gCOD products, the timestamp will still have the “:20.”
    • But if any field from the AgE dataset is included in the response, the timestamps on the hourly blocks of data will change to “:00” minutes, implying that all data in the response is representative of the hour, despite differing collection times.
  • Weighted average queries that explicitly specify products that are not included in the weighted average calculation will result in a validation error (e.g. …"?products=drivingDifficultyindex&weighted=true")

In response to requests from our customers, we have added two useful new features. Both offer insight into the characteristics of the grids used by each dataset, and provide the means for geospatial exploration that will help with API call economy. Details will be covered in the API documentation.

• Grid neighbor mapping
  • This new endpoint allows you to send the API a list of geolocations, and get back a map correlating the dataset’s “neighboring” grid points to groups of your locations for which that grid point would be representative (because it is their “nearest grid neighbor”). For example, you can send in a list of geolocations of business-relevant assets, and receive a presumably shorter mapping of actual grid points. This way, you can locally track and store those relationships, and economize your calls to the API by not making multiple calls that would result in the same grid data.
• Point in Poly
  • This new endpoint allows you to send the API a dataset and a polygonal geoshape, specified in WKT (well-known text), and receive a list of grid points contained in that geoshape. Sometimes we want to optimize API calls by querying geoshapes that contain multiple business assets. But we need to know how much waste there is (extra points we don’t need), and how many points will be in the response per hour in the time frame. This endpoint is the answer. These relationships could also be tracked and stored locally. One could name a polygon, and store its vertices and resulting gridpoints for a given dataset, resulting in useful and tactical reference data. It is important to note that geoshapes in this context will be subject to the same validations and size limitations that govern data queries via geoshape.

Should you have any questions or concerns, please email twcapi@us.ibm.com and include the subject line “HoD Direct updates” so we can swiftly address them.