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 and refresh your access token
Section titled “Reuse and refresh your access token”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.
Track changes to curves efficiently
Section titled “Track changes to curves efficiently”To monitor changes to a set of curves, follow these steps.
Step 1: Find the curves to track
Section titled “Step 1: Find the curves to track”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:
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=trueYou can also list all accessible curves. This is slow, so do it rarely:
curl -G -H "Authorization: Bearer $TOKEN" \ https://data-forecasts.volue.com/api/v1/timeseries/curves -d only_accessible=trueStep 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.
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.
Step 4: Fetch data for modified curves
Section titled “Step 4: Fetch data for modified curves”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.
Common mistakes
Section titled “Common mistakes”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/getin a loop. Search in batches instead (step 3). - Using free-text search for automation.
query=is for exploring. Search bynameinstead. - Fetching data for unchanged curves. Use
modified_sinceto find curves that changed since your last check (step 3).
Optimise your data queries
Section titled “Optimise your data queries”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:57ZThis fetches 51 tags across a year of issues in one request. To improve it:
- Fetch one issue at a time, for example
issue_date_from=2024-11-18T01:23:57Z&issue_date_to=2024-11-19T01:23:57Z. - Request fewer tags per request.
- Limit the date range with
data_fromanddata_to. - 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.
Fetch changes to historical data
Section titled “Fetch changes to historical data”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.
Find the curves that changed
Section titled “Find the curves that changed”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.
Time series
Section titled “Time series”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.
Tagged time series
Section titled “Tagged time series”As for time series, but fetch data for each tag.
Instance and tagged instance curves
Section titled “Instance and tagged instance curves”These curves have many issues. Find the issues that changed by searching across all instances
with modified_since, without data:
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=falseUse /instances/tagged/{id} for tagged instance curves. Then fetch data for each issue
found, with /instances/{id}/at.
Enable compression
Section titled “Enable compression”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.
Choose sensible polling intervals
Section titled “Choose sensible polling intervals”Polling more often than data changes wastes resources and gains nothing. Match your polling interval to how often the data updates.
Instance and tagged instance curves
Section titled “Instance and tagged instance curves”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:00GET /instances/tagged/1280?issue_date_from=2022-11-01T00:00:00&issue_date_to=2022-11-05T00:00:00Each 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.
Time series and tagged time series curves
Section titled “Time series and tagged time series curves”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.
Time-critical curves
Section titled “Time-critical curves”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.
Fetch only what you need
Section titled “Fetch only what you need”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.
Monitor your API usage
Section titled “Monitor your API usage”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.
Use caching
Section titled “Use caching”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 pointsFetching 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.