CDSAPI Operations

Functions
struct curl_slist *	customHeader (struct curl_slist *list, const option_t *options)
	Create a new header list for cURL with CDS API token field.
int	initializeHandle (CURL **handle, const struct curl_slist *headerList)
	Initialize cURL handle in place.
CURL *	newHandleWithOptions (struct curl_slist **list, const option_t *options)
	Create a new cURL handle and initialize it.
size_t	writeString (char *ptr, size_t size, size_t nmemb, void *userdata)
	Concatenate chunked response from API request into string.
size_t	discardWrite (char *ptr, size_t size, size_t nmemb, void *userdata)
	Discard delivered data from API request.
json_t *	getKeyRecursively (json_t *root, const char *key)
	Search JSON object recursively for a key with DFS and return first occurence.
json_t *	jsonArrayFromIntegers (const int *arr, size_t elements, const char *formatString)
	Convert an array of integers to their string representations with customizable formats.
char *	constructStringRequest (const int *years, const int *months, const int *days, const int *hours, const size_t yearsElements, const size_t monthsElements, const size_t daysElements, const size_t hoursElements, const OGREnvelope *aoi)
	Construct a JSON object for CDS API product request.
int	download (CURL *handle, const option_t *options, const OGREnvelope *aoi)
	Perform product request and download of ERA-5 products.
int	handleDownloadChain (CURL *handle, const option_t *options, const OGREnvelope *aoi, const char *outputPath, const int *subsetYears, const int *subsetMonths, const int *subsetDays, const int *subsetHours, const size_t yearsElements, const size_t monthsElements, const size_t daysElements, const size_t hoursElements, const unsigned int maxAttempts)
	Wrapper around chain of API requests needed to perform a download.
char *	cdsRequestProduct (CURL *handle, const int *years, const int *months, const int *days, const int *hours, const size_t yearsElements, const size_t monthsElements, const size_t daysElements, const size_t hoursElements, const OGREnvelope *aoi, const option_t *options)
	Perform product request with CDS API.
productStatus	cdsGetProductStatus (CURL *handle, const char *requestId, const option_t *options)
	Query the CDS API for the status of a previously created product request.
int	binaryExponentialBackoff (int attempt)
	Compute binary exponential backoff.
int	cdsWaitForProduct (CURL *handle, const char *requestId, const option_t *options, unsigned int maxAttempts)
	Wait for a product request to be downloadable with a binary exponential backoff.
int	cdsDownloadProduct (CURL *handle, const char *requestId, const char *outputPath, const option_t *options)
	Download data related to previously made request to local file.
int	cdsDeleteProductRequest (CURL *handle, const char *requestId, const option_t *options)
	Delete a prodcut request from personal CDS space.

Detailed Description

Function Documentation

binaryExponentialBackoff()

int binaryExponentialBackoff

(

int

attempt

)

Compute binary exponential backoff.

Parameters

attempt

Attempt for which binary exponential backoff should be computed.

Returns

int Seconds to wait until next attempt, -1 on overflow/underflow or when attempt is negative.

cdsDeleteProductRequest()

int cdsDeleteProductRequest	(	CURL *	handle,
		const char *	requestId,
		const option_t *	options )

Delete a prodcut request from personal CDS space.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
requestId	Request ID to delete.
CLI Arguments Parsing and Program Setup	Reference to parsed options.

Returns

int 0 on success, 1 on failure.

cdsDownloadProduct()

int cdsDownloadProduct	(	CURL *	handle,
		const char *	requestId,
		const char *	outputPath,
		const option_t *	options )

Download data related to previously made request to local file.

Note

This function assumes the order is already processed and ready to download.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
requestId	Request ID to download.
outputPath	File path to download file to.
CLI Arguments Parsing and Program Setup	Reference to parsed options.

Returns

int 0 on success, 1 on failure.

cdsGetProductStatus()

productStatus cdsGetProductStatus	(	CURL *	handle,
		const char *	requestId,
		const option_t *	options )

Query the CDS API for the status of a previously created product request.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
requestId	Request ID to query.
CLI Arguments Parsing and Program Setup	Reference to parsed options.

Returns

productStatus Product status.

cdsRequestProduct()

char * cdsRequestProduct	(	CURL *	handle,
		const int *	years,
		const int *	months,
		const int *	days,
		const int *	hours,
		const size_t	yearsElements,
		const size_t	monthsElements,
		const size_t	daysElements,
		const size_t	hoursElements,
		const OGREnvelope *	aoi,
		const option_t *	options )

Perform product request with CDS API.

This function performs the acutal request to the CDS API by constructing a suitable JSON payload and contact the correct API endpoint. The function returns the job/request ID assigned by CDS.

Note

After the function returns, the caller owns the returned object and musst free it.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
years	Reference to array of integers giving years to post request for.
months	Reference to array of integers giving months to post request for.
days	Reference to array of integers giving days to post request for.
hours	Reference to array of integers giving hours to post request for.
yearsElements	Number of entries in respective array.
monthsElements	Number of entries in respective array.
daysElements	Number of entries in respective array.
hoursElements	Number of entries in respective array.
aoi	Reference to a north-up bounding box with EPSG:4326 coordinates to restrict AOI, possibly NULL.
CLI Arguments Parsing and Program Setup	Reference to parsed options.

Returns

char* Job/Request ID, NULL on error.

cdsWaitForProduct()

int cdsWaitForProduct	(	CURL *	handle,
		const char *	requestId,
		const option_t *	options,
		unsigned int	maxAttempts )

Wait for a product request to be downloadable with a binary exponential backoff.

Note

An error is returned when the product request failed or a general error is encountered.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
requestId	Request ID to wait on.
CLI Arguments Parsing and Program Setup	Reference to parsed options.
maxAttempts	Maximum number of connections attempts to perform. This should be a rather high value as binary exponential backoff is used to increase time between connection requests.

Returns

int 0 on success, 1 on error.

constructStringRequest()

char * constructStringRequest	(	const int *	years,
		const int *	months,
		const int *	days,
		const int *	hours,
		const size_t	yearsElements,
		const size_t	monthsElements,
		const size_t	daysElements,
		const size_t	hoursElements,
		const OGREnvelope *	aoi )

Construct a JSON object for CDS API product request.

This function constructs a JSON object to use in API requests containing information about the years, months, days, hours and AOI to query a particular CDS API endpoint. This function is agnostic to any particular product or API endpoint as it simply packs above-mentioned data. If the parameter aoi is set to NULL, data for the entire globe is queried.

Note

After the function returns, the caller owns the returned object and musst free it.

Parameters

years	Reference to array of integers giving years to include in query.
months	Reference to array of integers giving months to include in query.
days	Reference to array of integers giving days to include in query.
hours	Reference to array of integers giving hours to include in query.
yearsElements	Number of entries in respective array.
monthsElements	Number of entries in respective array.
daysElements	Number of entries in respective array.
hoursElements	Number of entries in respective array.
aoi	Reference to a north-up bounding box with EPSG:4326 coordinates to restrict AOI, possibly NULL.

Returns

char* Reference to JSON-formatted product request or NULL on error.

customHeader()

struct curl_slist * customHeader	(	struct curl_slist *	list,
		const option_t *	options )

Create a new header list for cURL with CDS API token field.

Note

After the function returns, the caller owns the returned object and must free it with curl_slist_free_all after use.

This function may free the object pointed to by list when encountering an error.

Parameters

list	Reference to existing curl_slist to append to or NULL to create a new list.
CLI Arguments Parsing and Program Setup	Reference to parsed options.

Returns

struct curl_slist* Reference to cURL header list, NULL on error.

discardWrite()

size_t discardWrite	(	char *	ptr,
		size_t	size,
		size_t	nmemb,
		void *	userdata )

Discard delivered data from API request.

Note

This function is used as a callback for cURL and always returns size * nmemb.

Parameters

ptr	Reference to data chunk delivered to cURL.
size	Size of a byte in bytes, i.e. 1.
nmemb	Number of bytes delivered to cURL.
userdata	User data struct to store data in.

Returns

size_t Number of bytes handled by the callback.

download()

int download ( CURL * handle, const option_t * options, const OGREnvelope * aoi )

nodiscard

Perform product request and download of ERA-5 products.

This function takes options specified by the user and an envelope (possibly NULL) to query the CDS API, wait for successful processing and downloads file. A cURL handle is allocated and de-allocated for the scope of this function

Parameters

handle	Reference to allocated and initialized cURL handle
CLI Arguments Parsing and Program Setup	Reference to parsed options.
aoi	Reference to a north-up bounding box with EPSG:4326 coordinates to restrict AOI, possibly NULL.

Returns

int 0 on success, 1 on failure.

getKeyRecursively()

json_t * getKeyRecursively	(	json_t *	root,
		const char *	key )

Search JSON object recursively for a key with DFS and return first occurence.

Note

The returned reference is borrowed but its reference count is not chnaged. Thus, the object is only valid for the lifetime of root!

Parameters

root	Reference to root of JSON object.
key	Key to search for.

Returns

json_t* Reference to JSON object or NULL if key is not present.

handleDownloadChain()

int handleDownloadChain ( CURL * handle, const option_t * options, const OGREnvelope * aoi, const char * outputPath, const int * subsetYears, const int * subsetMonths, const int * subsetDays, const int * subsetHours, const size_t yearsElements, const size_t monthsElements, const size_t daysElements, const size_t hoursElements, const unsigned int maxAttempts )

nodiscard

Wrapper around chain of API requests needed to perform a download.

Note

Time frames for download are to be passed explicitly via arguments and not the options struct.

Parameters

handle	Reference to existing cURL handle used for request after duplication.
CLI Arguments Parsing and Program Setup	Reference to parsed options.
aoi	Reference to a north-up bounding box with EPSG:4326 coordinates to restrict AOI, possibly NULL.
outputPath	Reference to file path, no ownership is taken.
subsetYears	Reference to array of integers giving years to post request for.
subsetMonths	Reference to array of integers giving months to post request for.
subsetDays	Reference to array of integers giving days to post request for.
subsetHours	Reference to array of integers giving hours to post request for.
yearsElements	Number of entries in respective array.
monthsElements	Number of entries in respective array.
daysElements	Number of entries in respective array.
hoursElements	Number of entries in respective array.
maxAttempts	Maximum number of status requests made before request is deemed faulty.

Returns

int 0 on success, 1 on error.

initializeHandle()

int initializeHandle	(	CURL **	handle,
		const struct curl_slist *	headerList )

Initialize cURL handle in place.

This function sets the following options: CURLOPT_FOLLOWLOCATION to 1, CURLOPT_FAILONERROR to 1, CURLOPT_SSL_VERIFYHOST to 1, CURLOPT_TIMEOUT to 600 seconds (default value of cdsapi package), CURLOPT_USERAGENT to haze and possibly the additional headers.

Parameters

handle	Indirect reference to a pre-allocated cURL handle.
headerList	Reference to additional cURL headers or NULL.

Returns

int 0 on success, 1 on failure.

jsonArrayFromIntegers()

json_t * jsonArrayFromIntegers	(	const int *	arr,
		size_t	elements,
		const char *	formatString )

Convert an array of integers to their string representations with customizable formats.

Note

After the function returns, the caller owns the returned object and musst free it.

Parameters

arr	Reference to array of integers.
elements	Number of entries in respective array.
formatString	Format string to use when converting integers to their string representation, used for each element.

Returns

json_t* Reference to newly allocated JSON array or NULL on error.

newHandleWithOptions()

CURL * newHandleWithOptions	(	struct curl_slist **	list,
		const option_t *	options )

Create a new cURL handle and initialize it.

Note

After the function returns, the caller owns the returned object and must free it with after use.

Parameters

list	Indirect reference to list storing extra headers, needed beacuse cURL doesn't copy the list.
CLI Arguments Parsing and Program Setup	Reference to parsed options, used to access authentication token.

Returns

CURL* Reference to newly created cURL handle, NULL on error.

writeString()

size_t writeString	(	char *	ptr,
		size_t	size,
		size_t	nmemb,
		void *	userdata )

Concatenate chunked response from API request into string.

Note

This function is used as a callback for cURL

Parameters

ptr	Reference to data chunk delivered to cURL.
size	Size of a byte in bytes, i.e. 1.
nmemb	Number of bytes delivered to cURL.
userdata	User data struct to store data in (here: curlString).

Returns

size_t Number of bytes handled by the callback.