1. Die API
  2. Einführung

Informations-API: Eine Einführung Grundlagen zu unserer Informations-API und wie Sie die Daten für sich nutzen können

Grundlagen

Unsere Informations-API stellt viele Algorithmen, Daten und Echtzeit-Informationen zur Verfügung und ist ein Angebot an alle Software-Entwickler, Webseiten-Betreiber und jeden Nutzer, der Informationen, Tools und Berechnungen stabil, sicher und in Echtzeit benötigt.

Bieten Sie auch in Ihren Apps, Clockfaces oder Intranet-Applikationen das aktuelle Wetter an, lassen Sie sich die Twitter-Trends anzeigen oder nutzen Sie eine der zahlreichen Konvertierungsroutinen für Ihre Software. Jeder Account erhält kostenlos monatlich maximal 1000 Credits, die für API-Abrufe genutzt werden können. Für höhere Zugriffszahlen und professionelle Anwendungen können Credits kostenpflichtig gebucht werden, für Enterprise-Anwendungen können dedizierte Server bei uns gemietet werden.

Technische Grundlagen

Unsere Informations-API nimmt Ihre Anfragen per HTTP(S)-Request via GET oder POST entgegen, bearbeitet diese und liefert Ihnen die gewünschten Informationen zurück. Zum Senden und Empfangen der Daten unterstützt die API mehrere Datenaustausch-Formate wie JSON, URL-Encoding, XML und die Punktnotation.

Mehrere Info-Module können als Kette hintereinander abgearbeitet werden, Informationen können so direkt weiterverarbeitet werden.

Zur Nutzung der API ist zwingend ein API-Key nötig, den Sie auf Ihrer Profil-Seite kostenlos erstellen können.

Adressierung der API

Sie können die API über GET- und POST-Anfragen steuern, der URL der API lautet:

https://nettz.de/api.fcgi

Um beispielsweise per GET-Abfrage zu überprüfen ob die API reagiert, können Sie folgenden Aufruf nutzen:

https://nettz.de/api.fcgi?apikey=abcd1234&modul=system&action=alive

Die API antwortet dann beispielsweise mit folgenden Daten:

{
   "data" : {
      "version_api" : "0.9"
   },
   "status" : 1
}

data.version_api=0.9
status=1

data.version_api=0.9&status=1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt status="1">
  <data version_api="0.9" />
</opt>

API-Keys

Mit Hilfe von API-Keys identifizieren Sie sich bei der API - ohne gültigen API-Key ist keine Abfrage möglich. Bei den Beispielen in dieser Dokumentation verwenden wir zu Demonstrationszwecken den API-Key abcd1234. Wenn Sie das jeweilige Beispiel selbst testen möchten, müssen Sie abcd1234 zunächst durch Ihren eigenen API-Key ersetzen.

Die eBobs auf unserer Seite sind ohne API-Keys nutzbar, Sie müssen sich nur bei der direkten Nutzung unserer Informations-API authentifizieren.

API-Anfrage

Sie können die API über verschiedene Datenaustauschformate steuern, derzeit unterstützt werden JSON, XML, Key-/Value-Paare sowie die Punktnotation.

Übergeben Sie der API per GET oder POST ein gültiges Daten-Objekt in dem von Ihnen gewünschten Format:

{
   "action" : "alive",
   "apikey" : "abcd1234",
   "modul" : "system"
}

action=alive
apikey=abcd1234
modul=system

action=alive&apikey=abcd1234&modul=system
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt action="alive"
     apikey="abcd1234"
     modul="system" />

Zusätzliche Daten und Anweisungen können Sie über das data-Zweig übergeben:

Übergeben Sie ein JSON-Objekt als String via POST oder GET aus Ihrer Software:

{
   "action" : "forecast",
   "apikey" : "abcd1234",
   "data" : {
      "days" : 3,
      "location" : {
         "lat" : 12.34,
         "lng" : 56.78
      },
      "units" : "metric"
   },
   "modul" : "weather"
}

Nutzen Sie die Punktnotation, um die Daten per POST oder GET an die API zu übertragen:

action=forecast
apikey=abcd1234
data.days=3
data.location.lat=12.34
data.location.lng=56.78
data.units=metric
modul=weather

https://nettz.de/api.cgi?action=forecast&apikey=abcd1234&data.days=3&data.location.lat=12.34&data.location.lng=56.78&data.units=metric&modul=weather

Übertragen Sie die Parameter per XML an die API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt action="forecast" apikey="abcd1234" modul="weather">
  <data days="3" units="metric">
    <location lat="12.34" lng="56.78" />
  </data>
</opt>

API-Antwort

Wenn die API Ihre Anfrage durchlaufen und die gewünschten Daten bereitgestellt hat, erhalten Sie eine Antwort im gewünschten Datenformat. Jede API-Antwort enthält den Status-Code, der Ihnen Aufschluß darüber gibt, ob eine Aktion erfolgreich (status=1) oder mit einem Fehler (status=-1) abgeschlossen wurde.

Erfolgreiche Anfragen

Wenn Ihre Anfrage erfolgreich durchlaufen wurde, antwortet die API mit status=1. Die gewünschten Informationen Ihrer Anfrage finden sich im data-Teil der Antwort. Wenn Sie beispielsweise die action geo.code2country aufgerufen haben, kann die API-Antwort wie folgt aussehen:

{
   "data" : {
      "country" : "France"
   },
   "status" : 1
}

data.country=France
status=1

data.country=France&status=1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt status="1">
  <data country="France" />
</opt>

Fehlerhafte Anfragen

Wenn bei der Verarbeitung ein Fehler auftritt, bricht die API ab und liefert status=-1 zurück. Außerdem erhalten Sie in verschiedenen Fehler-Variablen weitere Informationen zum aufgetreteten Fehler:

{
   "errid" : "204",
   "errkey" : "countrycode",
   "errmsg" : "Missing key",
   "status" : -1
}

errid=204
errkey=countrycode
errmsg=Missing key
status=-1

errid=204&errkey=countrycode&errmsg=Missing%20key&status=-1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt errid="204"
     errkey="countrycode"
     errmsg="Missing key"
     status="-1" />

Erweiterte Antwort

Sie können mit Hilfe von options.verbose=1 einige zusätzliche Informationen zur Anfrage-Bearbeitung erhalten:

Übergeben Sie ein JSON-Objekt als String via POST oder GET aus Ihrer Software:

{
   "action" : "code2country",
   "apikey" : "abcd1234",
   "data" : {
      "countrycode" : "fr",
      "language" : "en"
   },
   "modul" : "geo",
   "options" : {
      "verbose" : 1
   }
}

Nutzen Sie die Punktnotation, um die Daten per POST oder GET an die API zu übertragen:

action=code2country
apikey=abcd1234
data.countrycode=fr
data.language=en
modul=geo
options.verbose=1

https://nettz.de/api.cgi?action=code2country&apikey=abcd1234&data.countrycode=fr&data.language=en&modul=geo&options.verbose=1

Übertragen Sie die Parameter per XML an die API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt action="code2country" apikey="abcd1234" modul="geo">
  <data countrycode="fr" language="en" />
  <options verbose="1" />
</opt>

In der Antwort finden Sie dann den Zweig verbose, in dem weitere Informationen zu Ihrer Anfrage bzw. der Antwort enthalten sind:

{
   "data" : {
      "country" : "France"
   },
   "status" : 1,
   "verbose" : {
      "credits" : "0.001",
      "duration_ms" : 0.0407688,
      "modulaction" : "geo.code2country",
      "timestamp" : 1578050973
   }
}

data.country=France
status=1
verbose.credits=0.001
verbose.duration_ms=0.0407688
verbose.modulaction=geo.code2country
verbose.timestamp=1578050973

data.country=France&status=1&verbose.credits=0.001&verbose.duration_ms=0.0407688&verbose.modulaction=geo.code2country&verbose.timestamp=1578050973
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt status="1">
  <data country="France" />
  <verbose credits="0.001"
           duration_ms="0.0407688"
           modulaction="geo.code2country"
           timestamp="1578050973" />
</opt>

In den Verbose-Informationen können Sie derzeit folgende Daten finden:

  • credits
    Die Credit-Gebühr, die für den Vorgang berechnet wurde.
  • duration_ms
    Die Dauer der reinen Berechnung Ihrer Anfrage in Millisekunden (ohne Empfang-/Senden-Teil)
  • modulaction
    Name des aufgerufenen Moduls und der Action, getrennt durch einen Punkt.
  • timestamp
    Hier finden Sie den Zeitstempel, an dem Ihre Anfrage abgeschlossen wurde.

Multiple Anfragen

Sie können der API auch mehrere Aktionen übergeben, die nacheinander als Kette abgearbeitet werden sollen. Selbstverständlich können Sie dabei mit Variablen in der Form %%varname%% arbeiten, um auf Daten vorheriger Ausführungen zurückzugreifen. Wenn Sie beispielsweise eine Abstimmung auf Ihrer Seite anbieten und bei jeder neuen Stimmabgabe eine Mail erhalten wollen, kombinieren einfach die beiden actions storage.vote und net.simplemail:

Übergeben Sie ein JSON-Objekt als String via POST oder GET aus Ihrer Software:

{
   "actions" : [
      {
         "action" : "vote",
         "apikey" : "abcd1234",
         "data" : {
            "store" : {
               "points" : "2",
               "userid" : "hans_dampf"
            },
            "storeid" : "Wahl Teamchef"
         },
         "modul" : "storage"
      },
      {
         "action" : "simplemail",
         "apikey" : "abcd1234",
         "data" : {
            "message" : "Points from hansdampf: 2\n\nThis was the %%LAST.data.report.count_votes%%. vote.\nAverage Points: %%LAST.data.report.average_points%%",
            "recipient" : "your@mail.adress",
            "sender" : "senders@mail.adress",
            "subject" : "New vote from hansdampf"
         },
         "modul" : "net"
      }
   ],
   "apikey" : "abcd1234"
}

Nutzen Sie die Punktnotation, um die Daten per POST oder GET an die API zu übertragen:

actions:0.action=vote
actions:0.apikey=abcd1234
actions:0.data.store.points=2
actions:0.data.store.userid=hans_dampf
actions:0.data.storeid=Wahl Teamchef
actions:0.modul=storage
actions:1.action=simplemail
actions:1.apikey=abcd1234
actions:1.data.message=Points from hansdampf: 2

This was the %%LAST.data.report.count_votes%%. vote.
Average Points: %%LAST.data.report.average_points%%
actions:1.data.recipient=your@mail.adress
actions:1.data.sender=senders@mail.adress
actions:1.data.subject=New vote from hansdampf
actions:1.modul=net
apikey=abcd1234

https://nettz.de/api.cgi?actions:0.action=vote&actions:0.apikey=abcd1234&actions:0.data.store.points=2&actions:0.data.store.userid=hans_dampf&actions:0.data.storeid=Wahl%20Teamchef&actions:0.modul=storage&actions:1.action=simplemail&actions:1.apikey=abcd1234&actions:1.data.message=Points%20from%20hansdampf:%202%0A%0AThis%20was%20the%20%25%25LAST.data.report.count_votes%25%25.%20vote.%0AAverage%20Points:%20%25%25LAST.data.report.average_points%25%25&actions:1.data.recipient=your@mail.adress&actions:1.data.sender=senders@mail.adress&actions:1.data.subject=New%20vote%20from%20hansdampf&actions:1.modul=net&apikey=abcd1234

Übertragen Sie die Parameter per XML an die API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt apikey="abcd1234">
  <actions action="vote" apikey="abcd1234" modul="storage">
    <data storeid="Wahl Teamchef">
      <store points="2" userid="hans_dampf" />
    </data>
  </actions>
  <actions action="simplemail" apikey="abcd1234" modul="net">
    <data message="Points from hansdampf: 2

This was the %%LAST.data.report.count_votes%%. vote.
Average Points: %%LAST.data.report.average_points%%" recipient="your@mail.adress" sender="senders@mail.adress" subject="New vote from hansdampf" />
  </actions>
</opt>

Erste Schritte

  1. Melden Sie sich kostenlos an und loggen Sie sich ein.

  2. Erstellen Sie einen API-Key auf Ihrer API-Key-Seite.

  3. Suchen Sie sich die gewünschten Info-Module zusammen

  4. Testen Sie den Abruf der gewünschten Daten mit unseren Live-Beispielen

  5. Integrieren Sie die Informationen via wget, PHP, Python, Perl, C++, Javascript usw. in Ihre App, Ihre Software oder Ihre Internetseite

Ihr Feedback zu dieser Seite

Sie vermissen weitere Infos oder Details auf dieser Seite oder haben einen Fehler gefunden? Bitte informieren Sie uns: