Eurostat Online Help for Data Browser
Child pages
  • API - Detailed guidelines - Asynchronous API

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Purpose of ASYNC API

The ASYNC APIis a programmatic access for asynchronous responses to large data requests.

For the different APIs listed above, data can be returned either synchronously or asynchronously:

  • Synchronously: the data is returned directly in the response to the request. This is the default operation

  • Asynchronously: the data is not returned directly in the response. Instead a key is returned in the response which allows to access the data through the async endpoint once it is available.

The decision whether to deliver the data synchronously or asynchronously is related to factors such as the complexity of the query and the volume of the data (number of rows) to be returned.

How to implement asynchronous requests?

The asynchronous delivery process can be summarized as follows:

  1. Step 1. A client issues a request to one of these asynchronous endpoints: CATALOGUE, SDMX 2.1. The API returns a response indicating asynchronous delivery pattern, with a unique key

  2. Step 2. The client issues to the asynchronous endpoint at regular interval a request with the unique key, to enquire about the availability readiness of the requested data

  3. Step 3. Once the data is available, the client receives the data attached in the response to the request for the unique key

Example

Step 1: Initial request

The initial request must be sent to one of the asynchronous endpoints mentioned above.

The response to such a request is structured as follows:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <ns0:syncResponse xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/extraction">
         <dataResponse>
            <queued>
               <id>98de05ea-540a-43d3-903b-7c9e14faf808</id>
               <status>SUBMITTED</status>
            </queued>
         </dataResponse>
      </ns0:syncResponse>
   </S:Body>
</S:Envelope>

The <id> value ("98de05ea-540a-43d3-903b-7c9e14faf808" in this example), is the key to use for checking data availability against the asynchronous endpoint.

Step 2: Get the current status of the request

The status of a request that is processed asynchronously can be one of the following values:

Value

Meaning

SUBMITTED

The request is submitted for processing

PROCESSING

The request is currently being processed

AVAILABLE

The data is available for download

EXPIRED

The request was processed but the data is no longer available

UNKNOWN_REQUEST

In case the key provided cannot be matched to a request

The current status of a given request can be obtained:

  • Via a REST request:

  • Via a SOAP request:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:asy="http://estat.ec.europa.eu/disschain/soap/asynchronous" xmlns:asy1="http://estat.ec.europa.eu/disschain/asynchronous">
   <soapenv:Header/>
   <soapenv:Body>
      <asy:async>
         <asy1:status>
            <asy1:key>98de05ea-540a-43d3-903b-7c9e14faf808</asy1:key>
         </asy1:status>
      </asy:async>
   </soapenv:Body>
</soapenv:Envelope>

This request may provide different results, depending on the current status of the request:

  • DATA_NOT_YET_AVAILABLE: As long as the request is not processed/finished, the following result will be returned:

    <S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <S:Fault>
         <faultcode>100</faultcode>
         <faultstring>DATA_NOT_YET_AVAILABLE: Requested data is not yet available for download. Check the status of your request.</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>

  • AVAILABLE: The request is processed/finished. When the query is fully executed, the returned status will be AVAILABLE and the following result will be returned:

    <S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <ns0:asyncResponse xmlns:ns1="http://estat.ec.europa.eu/disschain/asynchronous" xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/asynchronous">
         <ns1:status>
            <ns1:key>98de05ea-540a-43d3-903b-7c9e14faf808</ns1:key>
            <ns1:status>AVAILABLE</ns1:status>
         </ns1:status>
      </ns0:asyncResponse>
   </S:Body>
</S:Envelope>

Step 3: Get the data

When the results are AVAILABLE, it is possible to to download the data. Data can be obtained:

  • Via a REST request:

  • Via a SOAP request:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:asy="http://estat.ec.europa.eu/disschain/soap/asynchronous" xmlns:asy1="http://estat.ec.europa.eu/disschain/asynchronous">
   <soapenv:Header/>
   <soapenv:Body>
      <asy:async>
         <asy1:data>
            <asy1:key>98de05ea-540a-43d3-903b-7c9e14faf808</asy1:key>
         </asy1:data>
      </asy:async>
   </soapenv:Body>
</soapenv:Envelope>

When the results are returned, the data is attached to the SOAP response:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <ns0:asyncResponse xmlns:ns1="http://estat.ec.europa.eu/disschain/asynchronous" xmlns:ns0="http://estat.ec.europa.eu/disschain/soap/asynchronous">
         <ns1:data>
            <ns1:key>98de05ea-540a-43d3-903b-7c9e14faf808</ns1:key>
            <ns1:include href="cid:1568a7ca-792b-4730-bd81-a0a152eafd96"/>
         </ns1:data>
      </ns0:asyncResponse>
   </S:Body>
</S:Envelope>

Errors returned

Data not yet ready

As long as the data is not ready, the returned SOAP result will be:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <S:Fault>
         <faultcode>100</faultcode>
         <faultstring>DATA_NOT_YET_AVAILABLE: Requested data is not yet available for download. Check the status of your request.</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>
Invalid key

If the key provided is not valid, the returned SOAP result will be:

<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <S:Body>
      <S:Fault>
         <faultcode>100</faultcode>
         <faultstring>UNKNOW_REQUEST: Unknown request.</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>

Expand all   Collapse all
  • No labels
_