Skip to content
Documentation

Best practice

These recommendations help you get the best performance from the API and avoid common problems. Adapt them to your use case. Paths are relative to the base URL https://data-forecasts.volue.com/api/v1/timeseries.

Reuse your access token instead of requesting a new one for every call. Tokens are valid for 1 hour. Refresh the token after about 55 minutes, or when you get an HTTP 401 response. See Authentication.

Reuse your HTTP connection (keep-alive) across requests too.

To monitor changes to a set of curves, follow these steps.

Focus on the curves you need rather than querying all available curves. Define a search that matches them, store it in your code or configuration, and refresh the list periodically. Use only_accessible=true to get only curves you have access to:

Terminal window
curl -G -H "Authorization: Bearer $TOKEN" \
https://data-forecasts.volue.com/api/v1/timeseries/curves \
-d area=de -d category=wnd -d data_type=f -d only_accessible=true

You can also list all accessible curves. This is slow, so do it rarely:

Terminal window
curl -G -H "Authorization: Bearer $TOKEN" \
https://data-forecasts.volue.com/api/v1/timeseries/curves -d only_accessible=true

Step 2: Find the access range of your curves

Section titled “Step 2: Find the access range of your curves”

Your access to curve data is limited to the time periods in your agreement, for example from 2020-01-01 to the present. To avoid requesting data outside it, get and store the access range of each curve with GET /curves/{id}/access. If you only fetch recent data, you may not need this.

Step 3: Check for modified curves in batches

Section titled “Step 3: Check for modified curves in batches”

Keep track of when you last checked, and search only for curves modified since then.

  • Split your curve names into batches. Long lists can make the URL too long (see Curves).
  • Search the batches in parallel for faster results.
  • Repeat at an interval that suits your use case.
Terminal window
curl -G -H "Authorization: Bearer $TOKEN" \
https://data-forecasts.volue.com/api/v1/timeseries/curves \
--data-urlencode "name=pro dk1 wnd ec00 mwh/h cet min15 f" \
--data-urlencode "name=pro it-sici wnd ec00 mwh/h cet min15 f" \
--data-urlencode "modified_since=2025-12-19T06:00:00+01:00"

The response gives the modified time stamp of each curve:

[
{
"name": "pro dk1 wnd ec00 mwh/h cet min15 f",
"modified": "2025-12-19T06:47:32.15+01:00"
},
{
"name": "pro it-sici wnd ec00 mwh/h cet min15 f",
"modified": "2025-12-19T06:47:35.09+01:00"
}
]

As an example, checking 2000 curves in batches, with 5 requests in parallel, took less than 1 second. You can run this check quite often.

Once you know which curves changed, fetch their data:

  • Fetch only the periods you need. Do not fetch recent and historical data at the same frequency.
  • Keep the number of data points per request small. Requests of 15,000 data points or fewer normally take well under 1 second.
  • See Optimise your data queries and Fetch changes to historical data.

These create unnecessary load on your systems and ours. In the worst case they can lead to extra charges, if your usage exceeds your current tier.

  • Checking access repeatedly. Access rarely changes. Store it locally (steps 1 and 2).
  • Fetching metadata one curve at a time with GET /curves/get in a loop. Search in batches instead (step 3).
  • Using free-text search for automation. query= is for exploring. Search by name instead.
  • Fetching data for unchanged curves. Use modified_since to find curves that changed since your last check (step 3).

Make several requests with fewer data points rather than one request with many.

Counting data points:

  • One year, hourly: 24 × 365 = 8,760 data points
  • One year, 15-minute: 4 × 24 × 365 = 35,040 data points
  • One year, 15-minute, 3 tags: 4 × 24 × 365 × 3 = 105,120 data points
  • One day, 15-minute, 102 tags: 4 × 24 × 102 = 9,792 data points

The most common mistake is requesting many issues with many tags in one request. For example:

GET /instances/tagged/9913?tag=Avg&tag=01&tag=02&...&tag=51
&issue_date_from=2024-11-10T01:23:57Z
&issue_date_to=2025-11-19T01:23:57Z
&with_data=true
&data_to=2026-02-16T01:23:57Z

This fetches 51 tags across a year of issues in one request. To improve it:

  1. Fetch one issue at a time, for example issue_date_from=2024-11-18T01:23:57Z&issue_date_to=2024-11-19T01:23:57Z.
  2. Request fewer tags per request.
  3. Limit the date range with data_from and data_to.
  4. Check whether you need historical issues at all.

Usage that may lead to access restrictions

Section titled “Usage that may lead to access restrictions”

We monitor usage to keep service quality high for all customers. Excessive usage may lead to temporary restrictions or blocking. If your access is blocked, all requests return HTTP 403. We contact you at your registered email address to explain why and what to do. Depending on the severity, we may not be able to warn you in advance.

Any behaviour that causes poor latency for the API can lead to blocking. The most likely causes are:

  • Large requests. Requests for 400,000 data points or more put heavy load on our system. Many of them can degrade service for everyone, and we may limit or block access to restore normal service.
  • Too many requests. Very frequent requests can also lead to blocking.

Following the practices on this page keeps your usage within acceptable limits.

Most customers have a routine to fetch recently published data. This section is about keeping up with changes to historical data:

  • Time series and tagged time series: values written for times in the past.
  • Instance and tagged instance curves: issues with an issue date in the past.

We change historical data when, for example, an external source corrects an error (which can affect curves derived from it), or when we correct an error in our processing. With a few exceptions, we do not change data older than 1 year.

Decide which curves are worth checking for historical changes, and how far back. Then search for curves modified since your last check, in batches as in step 3. Add some overlap: if you check every 7 days, set modified_since to 7 days and 2 hours ago.

Group the results by curve_type (TIME_SERIES, TAGGED, INSTANCES, TAGGED_INSTANCES) and handle each type as below.

A time series curve has one time series, and the change can be anywhere in it. Fetch the full period you are interested in. Changes are normally within the last 365 days.

As for time series, but fetch data for each tag.

These curves have many issues. Find the issues that changed by searching across all instances with modified_since, without data:

Terminal window
curl -G -H "Authorization: Bearer $TOKEN" \
https://data-forecasts.volue.com/api/v1/timeseries/instances/11111 \
-d issue_date_from=2026-01-01 -d issue_date_to=2026-10-25 \
--data-urlencode "modified_since=2026-10-18T00:00:00Z" \
-d with_data=false

Use /instances/tagged/{id} for tagged instance curves. Then fetch data for each issue found, with /instances/{id}/at.

Set the request header Accept-Encoding: gzip to get compressed responses. This reduces the response size to about 25% of the uncompressed size and makes transfers much faster.

Polling more often than data changes wastes resources and gains nothing. Match your polling interval to how often the data updates.

Match your polling interval to the curve’s issue frequency. If a curve publishes once a day, polling every 5 minutes finds no change 99% of the time.

To see how often a curve updates, list its recent issues:

GET /instances/11111?issue_date_from=2022-11-01T00:00:00&issue_date_to=2022-11-05T00:00:00
GET /instances/tagged/1280?issue_date_from=2022-11-01T00:00:00&issue_date_to=2022-11-05T00:00:00

Each issue has a modified time stamp showing when it was last updated. Issues usually publish around the same time each day, but can be delayed by source or processing problems.

These curves have no issue dates, but their modified time stamp updates with each change. We do not keep a history of modified values, but you can watch the field to learn how often the curve updates.

For time-critical uses, use the Event API to get a notification when a curve changes, and fetch the data right away. There is a limit to how many curves one connection can listen to.

Most curves have a lot of historical data that rarely changes. Do not fetch large amounts of history with every update. Fetching less can also lower your subscription cost. When you need history, fetch it separately and less often.

Log your requests so you can track request frequency, the queries made, and the number of data points returned. This helps you find excessive or unnecessary requests. For more advanced monitoring, use tools such as Prometheus and Grafana to track request counts and data points over time.

Cache data locally where it makes sense, to reduce calls and data volume.

For example, an internal tool builds a 2-year hydro production report for Norway, Sweden, Denmark and Finland, with 4 hourly curves per country:

4 × 4 × 24 × 365 × 2 = 280,320 data points

Fetching this from the API every time someone opens the report is wasteful and increases your data volume. Instead, build the report once a day, cache it, and serve the cached version for the rest of the day.

© 2026 Volue.Version v0.6.38017 November 2026