API - Anfangen

Die API bietet verschiedene Endpunkte für verschiedene Zwecke:

• CATALOG, der für die Datenerkennung verwendet wird;

• STATISTICS verwendet für Datenabfragender und ersetzt JSON Webservice für Eurostat;

• SDMX 2.1, verwendet für synchrone Metadaten und Datenabfragen;

• ASYNC, verwendet für asynchrone Datenlieferung.

CATALOG-Endpunkte

Der CATALOG-Endpunkt dient der Datenerkennung und ist ein programmatischer Zugriff auf Datenkataloge. Der CATALOG-Endpunkt ist nur über REST verfügbar.

STATISTICS-Endpunkte

API Statistics ist ein Webdienst für Datenabfrage, dass die Parameter keine bestimmte Reihenfolge einhalten müssen.

Der Webdienst:

• stellt Daten im JSON-stat 2.0-Format bereit;

• unterstützt nur das REST-Protokoll (Representation State Transfer);

• liefert Antworten in englischer, französischer oder deutscher Sprache.

SDMX 2.1 Endpunkte

Die API SDMX-Endpunkte sind ein programmatischer Zugriff auf Metadaten und Daten, mit der Möglichkeit:

• Holen Sie sich eine vollständige Liste der öffentlich verfügbaren Datensätze

• Holen Sie sich die vollständige Strukturdefinition für ein bestimmtes Dataset

• Laden Sie einen Datensatz vollständig oder eine Teilmenge eines bestimmten Datensatzes herunter. Dies unterstützt benutzerdefinierte Anforderungen für Daten.

Die Verarbeitungszeit und die Datenantwort hängen von der Abfrage ab, d.h.

• Eine Anforderung für eine kleine Teilmenge einer Datenmenge könnte zu einer Antwort mit wenigen Kilobyte führen und innerhalb von Sekunden zurückgegeben werden

• Eine Anforderung für den vollständigen Datensatz kann zu einer Antwort von bis zu mehreren Megabyte führen und kann nach einigen Minuten zurückgegeben werden. Wenn diese Art von Anforderung gesendet wird, können asynchrone Anforderungen (nachfolgend beschrieben) nützlich sein.

Die Endpunkte für SDMX-Artefakte sind gemäß SDMX-technische Spezifikationen für Version 2.1.

Diese Endpunkte werden auch für die Rückgabe von Artefakten in anderen Formaten als SDMX 2.1 erweitert:

• JSON-Statistik

• TSV

• SDMX-CSV

ASYNC-Endpunkte für die asynchrone Antwortzustellung

Zweck der ASYNC-Endpunkte

Der ASYNC-Endpunkt ist ein programmatischer Zugriff für asynchrone Antworten auf große Datenanforderungen.

Für die verschiedenen oben aufgeführten Endpunkte können Daten entweder synchron oder asynchron zurückgegeben werden:

• Synchron: Die Daten werden direkt in der Antwort auf die Anfrage zurückgegeben. Dies ist die Standardoperation

• Asynchron: Die Daten werden nicht direkt in der Antwort zurückgegeben. Stattdessen wird in der Antwort ein Schlüssel zurückgegeben, der den Zugriff auf die Daten über den asynchronen Endpunkt ermöglicht, sobald dieser verfügbar ist.

Die Entscheidung, ob die Daten synchron oder asynchron geliefert werden sollen, hängt von Faktoren wie der Komplexität der Abfrage und der Menge der zurückzugebenden Daten (Anzahl der Zeilen) ab.

ASYNC-Endpunkte

Wie implementiert man asynchrone Anfragen?

Der asynchrone Auslieferungsprozess kann wie folgt zusammengefasst werden:

1. Schritt 1. Ein Client gibt eine Anforderung an einen dieser Endpunkte aus: CATALOG, SDMX 2.1. Die API gibt eine Antwort zurück, die ein asynchrones Zustellungsmuster mit einem eindeutigen Schlüssel angibt

2. Schritt 2. Der Client gibt in regelmäßigen Abständen eine Anfrage mit dem eindeutigen Schlüssel an den asynchronen Endpunkt aus, um nach der Verfügbarkeit der angeforderten Daten zu fragen

3. Schritt 3 Sobald die Daten verfügbar sind, empfängt der Client die Daten, die in der Antwort auf die Anforderung für den eindeutigen Schlüssel angehängt wurden

Beispiel

Schritt 1: Erstanfrage

Die ursprüngliche Anforderung muss an einen der oben genannten asynchronen Endpunkte gesendet werden.

Die Antwort auf eine solche Anfrage ist wie folgt aufgebaut:

<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>

Schritt 2: Rufen Sie den aktuellen Status der Anfrage ab

Der Status einer Anfrage, die asynchron verarbeitet wird, kann einer der folgenden Werte sein:

Der aktuelle Status einer bestimmten Anfrage kann abgerufen werden:

• Über eine REST-Anfrage:

  • URL anfordern: https://<api_base_uri>/1.0/async/status/<id>

  • Beispiel für eine URL-Anfrage: https://ec.europa.eu/eurostat/api/dissemination/1.0/async/status/98de05ea-540a-43d3-903b-7c9e14faf808

• Über eine SOAP-Anfrage:
  
  

  <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>

Diese Anfrage kann abhängig vom aktuellen Status der Anfrage unterschiedliche Ergebnisse liefern:

• DATA_NOT_YET_AVAILABLE: Solange die Anfrage nicht bearbeitet/abgeschlossen ist, wird folgendes Ergebnis zurückgegeben:
  
  

  <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: Die Anfrage wird bearbeitet / abgeschlossen. Wenn die Abfrage vollständig ausgeführt wird, ist der zurückgegebene Status AVAILABLE und das folgende Ergebnis wird zurückgegeben:

  <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>

Schritt 3: Laden Sie die Daten herunter

Wenn die Ergebnisse VERFÜGBAR sind, können die Daten heruntergeladen werden. Daten können abgerufen werden:

• Über eine REST-Anfrage:

  • URL anfordern: https://<api_base_uri>/1.0/async/data/<id>

  • Beispiel für eine URL-Anfrage: https://ec.europa.eu/eurostat/api/dissemination/1.0/async/data/98de05ea-540a-43d3-903b-7c9e14faf808

• Über eine SOAP-Anfrage:

  <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>

Wenn die Ergebnisse zurückgegeben werden, werden die Daten an die SOAP-Antwort angehängt:

<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>

Fehler zurückgegeben

Daten noch nicht bereit

Solange die Daten nicht bereit sind, lautet das zurückgegebene SOAP-Ergebnis:

<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>

Ungültiger Schlüssel

Wenn der angegebene Schlüssel nicht gültig ist, lautet das zurückgegebene SOAP-Ergebnis:

<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>