Heads-up: Forthcoming changes to API (REST & WS)

In support of some forthcoming changes to the way rain accumulation is calculated and presented in our apps, we will be pushing an update to the API next week. This message is purposely vague as to exactly what is changing, but that will become clear soon. The goal of this post is to give you enough information to make sure nothing breaks in your apps when we push the changes.

An important reason for this heads-up is that we will be removing two fields from the station observation: precip_accum_last_1hr and precip_accum_last_24hr - these guys were never officially documented, so hopefully none of your apps are using them. But please let us know if that’s not the case.

The main purpose of this update is the addition of five new elements to the end of the “obs” array within the SKY observation ("obs_sky"). That is, this array will be growing from 12 elements to 17 elements with no change to the first 12 elements. You may also notice the addition of several new “precip_*” fields to the station observation response. Please ignore all of these new values for now. We will explain what they mean soon.

Finally, there will also be some changes to the undocumented, unofficial “Summary Object” found in the AIR and SKY observation, but no one should be using those objects, right? If you are, please let us know ASAP.

Note: These changes only affect the REST and WS interfaces. They do not apply to the UDP interface.
Note also: These changes will not affect all devices at the same time. The number will start small and increase over time.

4 Likes

Hi @dsj!
Thanks for the heads-up. Unfortunately I do… Actually I’m using precip_accum_last_1hr from the REST API in Weather Station to:

  • provide “compatibility” (I should rather say “consistency”) with other brands of stations;
  • have the ability to push data of WeatherFlow stations to Met Office WOW and PWS Weather.

That’s a huge deal for me if this field disappears in the next week, I think. I have written the more “shock proof” code I can from my side, but I don’t know what will be the behavior of the ingestion systems from Met Office and PWS Weather if this field is missing or inconsistent…
I will do an impact assessment tomorrow and I will let you know.

Will this field be replaced by something equivalent?

Thanks.
Pierre

In the past you added ‘null’ values to the packets to keep the array the same in WS and UDP packets. Will you maintain that with the new changes?

If not please do so. This way we can use the same routines to parse WS and UDP packets.

Hi @dsj, I’m afraid I use fields from the “Summary Object” as well. In particular, I use ‘strike_last_epoch’, ‘strike_last_dist’, and ‘strike_count_3h’ from the summary provided in the SKY websocket message. I do this because it saves me an API call every minute to get the same details from the Station Observation endpoint. Can you let us know what the changes are going to be so we can plan to make changes to our applications is necessary?

Since you are using web socket data why are you not using the strike event packets?

I actually use both the strike event packets and the summary provided in the SKY websocket message. The reason is that the strike event packet doesn’t tell me about past events, or the number of strikes in the last three hours. So when the console first runs, it takes the ‘strike_last_epoch’ and ‘strike_last_dist’ of the last recorded strike from the SKY summary. Then for all following strikes, it uses the data in the strike events packet. As for the ‘strike_count_3h’, this is only provided by the SKY summary message.

1 Like

I understand. I have the same issues with UDP data. I want an API where we can query data per time period.

I ended up grabbing the Archive data for the last three hours and store it in an array. Then push and pull data. It works but is a lot of extra initial work.

So, I’ve made my impact assessment.
From a data sharing point of view, it’s not really annoying: for Met Office WOW and PWS Weather, this value is not mandatory. Even if I think it can modify some graphs for PWS Weather, this is not so catastrophic as what I had envisaged at first. :wink:
Finally, what is more annoying, is the disapearing of this value to compare stations directly in Weather Station. Will this value be replaced by something similar?
Thanks.

1 Like

My HomeSeer plug -in does make use of the precip_accum values but not in a user visible way. However, removing them will require me to update the plugin. Also, I suspect changes to the summary oject will also cause problems ans I am desearializing that using C# classes and the data types need to match or the deserialization fails.

I’m currently traveling out of the country with very poor internet access and may not be able to update my programs for a couple of weeks.

1 Like

Hi, yes I’m using both the fields precip_accum_last_1hr and precip_accum_last_24hr to upload data to Met Office (WOW), Open Weather Map (OWM) and PWS Weather and would like the retention of those fields.
Cheers
Ian

Ok, thanks for the feedback. We’re going to hold off removing anything for at least 30 days. Lightning strike info is not changing. We can probably keep the hourly precip values intact, since those are relatively easy to maintain. The 24hr versions are becoming a little unwieldy to support, however, so we’re going to need to drop them (and a few others - see below).

We are going ahead with the adds very soon (see below).

@bpaauwe let us know when you’ve updated your plug-in.

@veteranweatherman can you work-around not having the 24hr values in there?

Here is the full list of proposed ADDS, which should happen tomorrow (the meaning of these values will be explained at a later date - ignore them for now):

To be ADDED to the obs[] array within the SKY obs_sky{} object (REST & WS):

  • index 12: Precipitation Type
  • index 13: Wind Sample Interval
  • index 14: Precipitation Accumulation Final
  • index 15: Local Day Precipitation Accumulation Final
  • index 16: Precipitation Analysis Type

To be ADDED to the station observation response (REST):

  • precip_accum_local_yesterday_final
  • precip_analysis_type_yesterday
  • precip_minutes_local_day
  • precip_minutes_local_yesterday
  • precip_minutes_local_yesterday_final

And here is the full list of proposed REMOVES, which will happen in a couple weeks:

To be REMOVED from the station observation (REST):

  • precip_accum_last_24hr

To be REMOVED from the undocumented summary{} object in the SKY device observation (REST & WS):

  • precip_total_24h
  • precip_high_24h
  • precip_high_epoch_24h

To be REMOVED the undocumented summary{} object in the AIR device observation (REST & WS):

  • pressure_high_24h
  • pressure_low_24h
3 Likes

Thanks for keeping us in the loop. I shouldn’t have to make any changes to the PiConsole.

Sorry, I forgot to answer this yesterday, Gary. The answer is yes.

Just so everyone, mostly me, is clear, there will be UDP changes in a future firmware so the obs array indexes match.

Correct. If we add fields to the obs[] array in the UDP obs_sky message, we will pad it with nulls for these api-level additions in order to keep the two obs_sky objects compatible. Another way to say it is that the length of the obs[] array may differ, depending on where you see it, but the meaning of any particular element of that array will always agree. Clear?

2 Likes

What you said is clear but I am more concerned with the length of the obs[[]] being the same so the same code can be used to extract data and not be dependent on where it came from.

Eventually the obs arrays will all match but hopefully your code can handle variable length arrays, which can happen for different reasons (old firmware, etc.)

1 Like

Of course it can. But as everything else, I spend more on error checking code than on actual data. :smile:

2 Likes

That’s great news. Thanks for the clarification @dsj :slight_smile:

Now we look forward, with confidence, to the definition of the new fields :innocent:

3 Likes