QR Code API: Befehl „read-qr-code“ (QR Code lesen / scannen, QR Code Reader)

Inhaltsverzeichnis

1.0 Allgemeines

Auf dieser Seite wird der Befehl read-qr-code unserer QR Code API („Application Programming Interface“, Programmierschnittstelle) beschrieben.

Mit diesem Befehls können Sie selbst einen QR Code lesen (programmieren Sie sich z.B. Ihren persönlichen QR Code Reader).

1.1 Nutzungsbedingungen

Siehe Nutzungsbedingungen: QR Code API.

Sonstige, ggf. nützliche Informationen: Es gibt kein API-Anfragen-Limit. Dennoch behalten wir uns das Recht vor, API-Anfragen abzulehnen. Dies gilt insbesondere für Anfragen, welche wir als missbräuchlich oder unangebracht interpretieren (zum Beispiel weil es sich offensichtlich um eine DoS-Attacke handelt). Zu diesem Zwecke loggen wir die Herkunft aller Aufrufe (Referrer sowie IP-Adresse), jedoch nicht die QR Code-Inhalte. Um uns die Arbeit zu erleichtern, lassen Sie uns am Besten wissen, wenn Sie denken, dass Ihr Dienst regelmäßig mehr als 10 000 Anfragen pro Tag verursacht oder Ihr Dienst Ihrer Meinung nach zu unrecht geblockt wird.

2.0 Schnelleinstieg

Stellen Sie einen GET-Request der folgenden Form an unser System, um eine QR Code-Grafik auszulesen (also einen QR Code im Web zu scannen):
http(s)://api.qrserver.com/v1/read-qr-code/?fileurl=[URL-codierte-Webadresse-zu-Bilddatei-mit-QR-Code]

Probieren Sie es direkt in Ihrem Browser aus indem Sie die folgende URL aufrufen, um den QR Code unter http://api.qrserver.com/v1/create-qr-code/?data=HelloWorld auszulesen:

http://api.qrserver.com/v1/read-qr-code/?fileurl=http%3A%2F%2Fapi.qrserver.com%2Fv1%2Fcreate-qr-code%2F%3Fdata%3DHelloWorld

3.0 Parameter

Ihnen stehen eine Reihe von Parametern zu Verfügung um das Auslesen / Scannen eines QR Codes zu steuern. Hängen Sie bei einem GET-Request zusätzliche Parameter einfach via &[parameter-name]=[parameter-wert] an Ihre Anfrage an.

Alle Parameter können via HTTP-GET oder -POST übergeben werden (mit Ausnahme des POST-only-Parameters file). Auch ein Mix beider Methoden ist möglich. Bei gleichzeitiger Angabe eines Parameters via POST und GET wird der Wert des GET-Parameters bevorzugt.

3.1 fileurl-Parameter

Adresse (URL) einer via Internet aufrufbaren Grafikdatei, welche den auszulesenden QR Code enthält (z.B. ein Foto).

  • Format:
    [URL]. Die Adresse muss URL codiert übergeben werden, PHP-Programmierer können z.B. urlencode() nutzen. Zudem muss die Datei für unsere Server über das Internet erreichbar sein und auf eine Grafik im Format PNG, GIF oder JP(E)G verweisen, welches kleiner als 1 MiB ist. Nutzen Sie HTTP- statt HTTPS-URLs, sofern dies aus sicherheitstechnischer Sicht möglich ist. Dies beschleunigt den Ablauf und verhindert auf Zertifikatsfehlern basierende Download-Probleme.
  • Gültige Beispiele:
    http%3A%2F%2Fapi.qrserver.com%2Fv1%2Fcreate-qr-code%2F%3Fdata%3DHelloWorld
    (URL-encodiert, entspricht http://api.qrserver.com/v1/create-qr-code/?data=HelloWorld im Klartext)
  • Fehlerhafte Beispiele:
    www.example.com/qrcode.png (ungültige QR-Code-URL, Protokollangabe wie http:// fehlt)

3.2 file-Parameter

Eine Grafikdatei (z.B. ein Foto) welches den auszulesenden QR Code enthält als direkter Upload für die API (nur mittels HTTP-POST-Request möglich). Bitte beachten Sie, dass der file-Parameter ignoriert wird, sofern fileurl angegeben wurde. Sie können also nicht gleichzeitig eine externe Datei via fileurl auslesen und eine Grafik über file an unseren Server hochladen.

  • Format:
    Die zu lesende Bilddatei selbst (Content-Type: multipart/form-data). Die Grafik muss im Format PNG, GIF oder JP(E)G vorliegen und kleiner als 1 MiB sein.
  • Beispiel eines QR-Code-Upload-Formulars:
    <html>
    <form enctype="multipart/form-data" action="http://api.qrserver.com/v1/read-qr-code/" method="POST">
    <!-- MAX_FILE_SIZE (maximale Dateigröße in Bytes) muss vor dem input-Feld
        angegeben werden, über welches die QR Code Grafik hochgeladen wird -->
    <input type="hidden" name="MAX_FILE_SIZE" value="1048576" />
    <!-- Der "name" des Input-Felds muss "file" lauten, da es sich dabei um den
       Namen des POST-Parameters handelt -->
    Zu lesende / scannende QR Code-Grafik auswählen: <input name="file" type="file" />
    <input type="submit" value="QR Code lesen" />
    </form>
    </html>

3.3 outputformat-Parameter

Das Format, in welchen die ausgelesenen QR Code-Daten oder Fehlermeldungen ausgegeben werden sollen. Bitte beachten Sie, dass bei einer Bilddatei die mehrere QR Codes enthält derzeit nur jeweils der erste gefundene QR Code ausgelesen wird. Dies gilt auch für mittels „Structured Append“ zusammengesetzte QR Codes. Zukünftige QR Code-API-Versionen werden gegebenenfalls auch mehrere QR Codes lesen können (inkl. „Structured Append“). Die JSON- bzw. XML-Antwort ist bereits dafür vorbereitet.

  • Mögliche Werte:
    json
    xml
  • Fehlerhafte Beispiele:
    JSON (falsche Schreibweise, alles groß statt klein)
    Xml (falsche Schreibweise, erster Buchstabe groß statt klein)
  • Default (wird verwendet wenn keine oder fehlerhafte Angabe erfolgt):
    json
  • Rückmeldung, falls der QR Code gelesen werden konnte:
    • XML-Format:
      <?xml version="1.0" encoding="UTF-8"?>
      <barcodes>
      <barcode type="qrcode">
         <symbol seq="0">
             <data><![CDATA[Inhalt des gelesenen QR Codes]]></data>
             <error />
         </symbol>
      </barcode>
      </barcodes>
    • JSON-Format:
      [
      {
         "type": "qrcode",
         "symbol": [
             {
                 "seq": 0,
                 "data": "Inhalt des gelesenen QR Codes",
                 "error": null
             }
         ]
      }
      ]
  • Fehlermeldung, falls das QR Code lesen fehlgeschlagen ist:
    • XML-Format:
      <?xml version="1.0" encoding="UTF-8"?>
      <barcodes>
      <barcode type="qrcode">
         <symbol seq="0">
             <data />
             <error>Fehlerbeschreibung, z.B. "download error (could not establish connection)"</symbol>
         </symbol>
      </barcode>
      </barcodes>
    • JSON-Format:
      [
      {
         "type": "qrcode",
         "symbol": [
             {
                 "seq": 0,
                 "data": null,
                 "error": "Fehlerbeschreibung, z.B. \"download error (could not establish connection)\""
             }
         ]
      }
      ]