Mai 2021
Bei Fragen wenden Sie sich bitte einfach an uns.
Freewave stellt seine Standortdaten für (Web-)Applikationen unter folgenden Bedingungen kostenlos zur Verfügung:
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.
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.
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.
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.
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>
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. |
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 |
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 |
Eigenschaft | Beschreibung | Wert/Beispiel |
uid |
UID der Kategorie | 1 |
nameDE |
Name der Kategorie auf Deutsch. | Kino |
nameEN | Name der Kategorie auf Englisch. | Cinema |
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]
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. |
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. |
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). |
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). |
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. |
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. |
Beschreibung: | Gibt sämtliche Änderungen an der Hotspotliste und der Kategorien seit einem bestimmten Zeitpunkt unterteilt in added, updated 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. |
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. |
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. |