| 
  • If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Freewave API Dokumentation

Page history last edited by Walter Krivanek 2 years, 10 months ago


Stand

Mai 2021

Bei Fragen wenden Sie sich bitte einfach an uns.

 

Nutzungsbedingungen

Freewave stellt seine Standortdaten für (Web-)Applikationen unter folgenden Bedingungen kostenlos zur Verfügung:

  1. Bitte nur notwendige Anfragen an die API senden und die Limitierung beachten.
  2. Der Datenstand der Applikation muss mindestens täglich aktualisiert werden. 
  3. Als Datenquelle bitte Freewave angeben (inkl. Link auf www.freewave.at & Einsatz des Freewave Logos).
  4. Jeder Standort sollte darüber hinaus deutlich als Freewave Hotspot ausgewiesen werden, bei Kartenansichten bitte möglichst den Freewave Pin einsetzen.
  5. Eine Datenweitergabe an Dritte, die über das Veröffentlichen über die Website/Applikation hinaus geht, ist nur nach schriftlicher Genehmigung von Freewave gestattet.
  6. Die Weitergabe des API-Schlüssels ist nicht erlaubt.

    Um einen API-Schlüssel zu erhalten, genügt eine E-Mail mit der beabsichtigten Verwendung und den Kontaktdaten eines Ansprechpartners, sofern diese vom Absender abweichen.

  7. Der User-Agent der zugreifenden Applikation sollte eindeutig benannt werden. Dies erleichtert uns etwaigen technischen Support.

 

Allgemeines

 

API Schlüssel

Mit jeder Anfrage an die API muss ein API Schlüssel mitgeschickt werden. Durch den API Schlüssel wird nicht der Endnutzer, sondern die Applikation identifiziert. Kontaktieren Sie uns bitte mit einer kurzen Beschreibung Ihrer Applikation, um einen API Schlüssel für Ihre Applikation zu erhalten.

 

Frequenzlimitierung

Alle Anfragen an die Freewave API unterliegen einer Frequenzlimitierung. Im Normalfall liegt diese bei 60 Anfragen pro 60 Minuten, gemessen ab der ersten Anfrage. Übertritt ein Client dieses Limit, wird er über einesprechende Fehlermeldung im gewünschten Format mit dem HTTP Status Code 400 darüber informiert.

Sollte ein Client diese Fehlermeldung über einen gewissen Zeitraum hinaus ignorieren und weiter Anfragen an den API Server senden, wird die IP-Adresse dieses Clients für einen längeren Zeitraum komplett gesperrt.

Sollte diese Limitierung für Ihre Applikation zu restriktiv sein, kontaktieren Sie uns, damit wir Ihre Limitierung individuell anpassen können.

Um einen Überblick über verbleibende Anfragen zu haben, werden mit jeder Antwort die Eckdaten der Limiterung in den HTTP Kopfdaten mitgeschickt.

  • X-RateLimit-Limit: Die Limitierung der Anfragen, z.B. 60.
  • X-RateLimit-Remaining: Die Anzahl der noch möglichen Anfragen bis zum Reset
  • X-RateLimit-Reset: Der Zeitpunkt, wann dieses Limit zurückgesetzt wird (standardmäßig nach 60 Minuten nach der jeweils ersten Anfrage) im Unix-Zeitformat.

 

Formate und Kodierung

Derzeit antwortet die Freewave API im XML-Format. JSON, PLIST und weitere Formate sind bereits in Arbeit.

Alle Antworten der Freewave API werden mit der UTF-8 Zeichenkodierung kodiert.

 

Fehlermeldungen

Die Freewave API gibt Fehlermeldungen immer im gewünschten Format (sofern bekannt) und mit einer sprechenden Fehlermeldung auf Englisch zurück. Hier ein Beispiel im XML-Format:

<?xml version="1.0" encoding="UTF-8"?>
<error>
     <request>/v2/hotspots/2320000x.xml</request>
     <message>No hotspot(s) found.</message>
</error>

 

HTTP Status Codes

Bei allen Antworten, inklusive Fehlermeldungen, werden passende HTTP Status Codes zurückgegeben. Folgende kommen dabei zur Anwendung:

Code Bedeutung Erklärung
200 OK Die Anfrage wurde erfolgreich bearbeitet.
304 Not Modified Es stehen keine neuen Daten seit der letzten Anfrage zur Verfügung.
400 Bad Request Die Anfrage war Fehlerhaft. Bitte beachten Sie die zurückgegebene Fehlermeldung.
404 Not Found Die Anfrage brachte kein Ergebnis bzw. wurde ein falscher Pfad verwendet.
500 Internal Server Error Ein Fehler ist aufgetreten. Im Normalfall werden die Serveradministratoren automatische davon in Kenntnis gesetzt.
503 Service Unavailable Der API Server ist überlastet.

 

Eigenschaften eines Hotspots

Eine Anfrage an den Freewave-API-Server gibt, je nach Art, alle oder einige Hotspots mitsamt ihren Eigenschaften zurück. Dies sind die Eigenschaften:

Eigenschaft Beschreibung Wert/Beispiel
uid UID des Hotspots. 23200001
name Name des Hotspots. Café Freewave
street1 Adresse des Standorts. Premlechnergasse 12
street2 Zusatzinformationen zur Adresse.  
postalCode Die Postleitzahl. 1120
city Die Stadt. Wien
country Das Land nach ISO 3166-1-alpha-2. at
phone Die Telefonnummer des Standorts im internationalen Format. +4318040134
email Die E-Mail Adresse des Standortes. office@freewave.at
url Die URL der Website des Standortes. https://www.freewave.at
latitude Die geographische Breite des Standortes. 48.19559
longitude Die geographische Länge des Standortes. 16.35333
coverage Die Abdeckung des WLAN Netzes. complete für den kompletten Standort. public-areas für öffentliche Bereiche wie z.B. eine Hotellobby.
logoSmall Die URL zu dem Logo des Standortes im kleinen Format (32x32 Pixel). Das Bild kann ein GIF, JPG oder PNG sein. http://static.freewave.at/logos/freewave_32.gif
logoMedium Die URL zu dem Logo des Standortes im mittleren Format (64x64 Pixel). Das Bild kann ein GIF, JPG oder PNG sein. http://static.freewave.at/logos/freewave_64.gif
logoLarge Die URL zu dem Logo des Standortes im großen Format (150x150 Pixel). Das Bild kann ein GIF, JPG oder PNG sein. http://static.freewave.at/logos/freewave_150.gif
status Der derzeitige Funktionsstatus des Hotspots.
Wird optional ausgegeben.
online im Normalzustand, offline bei temporären Ausfällen.
statusMessage Zusatzinformation zum Status.
Wird optional ausgegeben.

z.B.: Leitungsstörung

categories
Kategorie-ID oder kommagetrennte Liste der Kategorie-IDs. 1,3

 

Eigenschaften einer Hotspot-Kategorie

Eigenschaft Beschreibung  Wert/Beispiel 

uid

UID der Kategorie 

nameDE

Name der Kategorie auf Deutsch.  Kino 
nameEN Name der Kategorie auf Englisch. Cinema 

 

Anfragen

Die URI einer Anfrage an die Freewave API setzt sich aus folgenden Teilen zusammen:

https://api.freewave.at/v2/pfad.format?apikey=api-schlüssel[&weitere=parameter]

  • Pfad: Es gibt mehrere Pfade, die unterschiedliche Ergebnisse ausgeben (siehe weiter unten).
  • Format: Die Dateierweiterung des gewünschten Formats, also z.B.: json (siehe Punkt Formate und Kodierung)
  • API-Schlüssel: Ihr API Schlüssel (siehe Punkt API Schlüssel)
  • Weitere Parameter: Manche Befehle erlauben weitere oder optionale Parameter.

 

Alle Hotspots

Beschreibung: Gibt alle Hotspots in einer Liste aus.
URI: /v2/hotspots.format
HTTP Methode: GET
Variablen: format
Das gewünschte Format (z.B.: json).
Parameter: country (optional)
Das Land nach ISO 3166-1-alpha-2, z.B. at für Österreich. Die Liste wird damit auf dieses Land
beschränkt.
postcode (optional)
Die Postleitzahl, also z.B. 1120. Die Liste wird damit auf diese Postleitzahl beschränkt. Wird eine Postleitzahl aber kein Land angegeben, wird automatisch Österreich als Land gewählt.
status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben.

 

Alle Hotspots inkl. Kategorien

Beschreibung: Gibt alle Hotspots und Kategorien in einer gemeinsamen Liste aus.
URI: /v2/hotspots+categories.format
HTTP Methode: GET
Variablen: format
Das gewünschte Format (z.B.: json).
Parameter: country (optional)
Das Land nach ISO 3166-1-alpha-2, z.B. at für Österreich. Die Liste wird damit auf dieses Land
beschränkt.
postcode (optional)
Die Postleitzahl, also z.B. 1120. Die Liste wird damit auf diese Postleitzahl beschränkt. Wird eine Postleitzahl aber kein Land angegeben, wird automatisch Österreich als Land gewählt.
status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben. 

 

Alle Kategorien

Beschreibung: Gibt alle Kategorien aus.
URI: /v2/categories.format
HTTP Methode: GET
Variablen: format
Das gewünschte Format (z.B.: json).

 

Einzelner Hotspot

Beschreibung: Gibt einen einzelnen Hotspot zurück.
URI: /v2/hotspots/uid.format
HTTP Methode: GET
Variablen: uid
Die eindeutige Identifikation des Hotspots (z.B.: 23200001).
format
Das gewünschte Format (z.B.: json).
status (optional)
Bei dem Wert yes wird auch der Status des Hotspots ausgegeben.

 

Einzelne Kategorie

Beschreibung: Gibt eine einzelne Kategorie zurück.
URI: /v2/categories/uid.format
 
HTTP Methode: GET
Variablen: uid
Die eindeutige Identifikation der Kategorie (z.B.: 1).
format
Das gewünschte Format (z.B.: json).

 

Status eines einzelnen Hotspots

Beschreibung: Gibt den Status und die optinale Status-Message dazu eines einzelnen Hotspots zurück.
URI: /v2/hotspots/uid/status.format
HTTP Methode: GET
Variablen: uid
Die eindeutige Identifikation des Hotspots (z.B.: 23200001).
format
Das gewünschte Format (z.B.: json).

 

Neueste Hotspots

Beschreibung: Gibt die x neuesten Hotspots aus.
URI:

/v2/hotspots/latest.format

URI: /v2/hotspots/latest/anzahl.format
HTTP Methode: GET
Variablen: format
Das gewünschte Format (z.B.: json).
anzahl
Die gewünschte Anzahl (z.B.: 20).
Parameter: country (optional)
Das Land nach ISO 3166-1-alpha-2, z.B. at für Österreich. Die Liste wird damit auf dieses Land
beschränkt.
postcode (optional)
Die Postleitzahl, also z.B. 1120. Die Liste wird damit auf diese Postleitzahl beschränkt. Wird eine Postleitzahl aber kein Land angegeben, wird automatisch Österreich als Land gewählt.
status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben.

 

Änderungen seit einem Zeitpunkt

Beschreibung: Gibt sämtliche Änderungen an der Hotspotliste seit einem bestimmten Zeitpunkt unterteilt in
added, updated und deleted zurück. Ideal um bestehende Listen zu aktualisieren.
URI: /v2/hotspots/since/datum.format
HTTP Methode: GET
Variablen: datum
Das Datum im W3C-Format, also z.B. 2009-04-08T14:00:00Z oder 2009-04-08T14:00:00+02:00.
format
Das gewünschte Format (z.B.: json). 
Parameter: status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben.

 

Änderungen seit einem Zeitpunkt (mit Kategorien)

Beschreibung: Gibt sämtliche Änderungen an der Hotspotliste und der Kategorien seit einem bestimmten Zeitpunkt unterteilt in
addedupdated und deleted zurück. Ideal um bestehende Listen zu aktualisieren.
URI: /v2/hotspots+categories/since/datum.format
HTTP Methode: GET
Variablen: datum
Das Datum im W3C-Format, also z.B. 2009-04-08T14:00:00Z oder 2009-04-08T14:00:00+02:00.
format
Das gewünschte Format (z.B.: json). 
Parameter: status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben.

 

Änderungen der Kategorien seit einem Zeitpunkt

Beschreibung:

Änderungen der Kategorien (betrifft nur Namensänderungen) seit einem Zeitpunkt.

(Änderungen der Kategorie-Zuordnungen sind Änderungen der Hotspots.)

URI: /v2/categories/since/datum.format
HTTP Methode: GET
Variablen: datum
Das Datum im W3C-Format, also z.B. 2009-04-08T14:00:00Z oder 2009-04-08T14:00:00+02:00.
format
Das gewünschte Format (z.B.: json). 
Parameter: status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben. 

 

Hotspots in der Umgebung

Beschreibung: Gibt Hotpots in der Umgebung der genannten Koordinaten zurück.
URI: /v2/hotspots/near/latitude+longitude.format
HTTP Methode: GET
Variablen: latitude
Die geographische Breite (z.B.: 48.19559).
longitude
Die geographische Länge (z.B.: 16.35333).
format
Das gewünschte Format (z.B.: json).
status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben.
Parameter: metrics (optional, standardmäßig km)
Die gewünschte Einheit der Längenmaße. Erlaubte Werte: km für Kilometer, mi für Meilen.
radius (optional, standardmäßig 10)
Der Radius, in dem sich die Hotspots befinden dürfen. Bezieht sich auf metrics.
limit (optional)
Gibt die maximale Anzahl der ausgegebenen Hotspots an.
status (optional)
Bei dem Wert yes werden auch jeweils die Status der Hotspots ausgegeben. 

  

Comments (0)

You don't have permission to comment on this page.