Dieses Dokument beschreibt die REST-Schnittstellen für Angebote.
| User Story | Ein User kann ein Angebot mit Hilfe der Angebots-ID abfragen. |
| HTTP | GET |
| URL |
| User Story | Ein User kann ein Angebot mit Hilfe der seiner External-ID abfragen. |
| HTTP | GET |
| URL | http://api.mairdumont.com/data/offer/api/offer/external/?user=&lang=de |
| User Story | Ein User kann die Angebote abfragen, die einer Destination zugeordnet sind. |
| HTTP | GET |
| URL | http://api.mairdumont.com/data/destination/api/destination//?lang=de&filter=offer |
Da nicht alle Partner ihre Angebote mit Koordinaten angereichert haben, erfolgt die Suche über einen Geocode indirekt über die Suche nach Destinationen. Dazu werden Destination gesucht, bei denen der gesuchte Geocode im Polygon der Destination liegt. Die Angebots-Suche erfolgt dann mit den DestinationIds der gefundenen Destinationen. Ist der gesuchte Geocode in keinem Destination-Polygon enthalten, so findet auch keine Suche statt.
| User Story | Ein User kann die Angebote über einen Geocode abfragen. |
| HTTP | GET |
| URL | http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=\, |
| User Story | Ein User kann sich zusammen mit einer Suchanfrage die Facette der Attribute ausgeben lassen. Dies erfolgt über den Parameter "facet" mit de Wert "attribution". |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&facet=attribution |
| User Story | Ein User kann Abfragen der Angebote auf Suchbegriffe einschränken. |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&search=Teambuilding <http://api.mairdumont.com/data/destination/api/destination/>/?lang=de&filter=offer&search=Teambuilding |
| User Story | Ein User kann Abfragen der Angebote auf einzelne Angebots-Partner einschränken. |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&channel=[,] <http://api.mairdumont.com/data/destination/api/destination/>/?lang=de&filter=offer&channel=[,] |
| User Story | Ein User kann Abfragen der Angebote auf Mindest- und Höchstpreise einschränken. |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&maxPrice=15 <http://api.mairdumont.com/data/destination/api/destination/>/?lang=de&minPrice=5.5&maxPrice=15 |
| User Story | Ein User kann Abfragen der Angebote auf Mindest- und Höchstdauer einschränken. Die Dauer wird in Minuten angegeben, z.B. 120 für 2 Stunden. |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&maxDuration=180 http://api.mairdumont.com/data/destination/api/destination//?lang=de&minDuration=45&maxDuration=90 |
| User Story | Ein User kann Abfragen der Angebote auf Kategorien einschränken. Die gewünschten Kategorien werden über den Parameter "cat" als kommaseparierte Liste von IDs übergeben. |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&cat=5,6 http://api.mairdumont.com/data/destination/api/destination//?lang=de&cat=5,6 |
| User Story | Ein User kann Abfragen der Angebote auf Attribute einschränken. Die gewünschten Attribute werden über den Parameter "attr" übergeben. Ist eine Oder-Verknüpfung gewünscht, dann müssen die Attribute als Wert eines Parameters übergeben werden, z.B. "attr=afoot cycling". Ist eine Und-Verknüpfung gewünscht, dann müssen die Werte als eigene Parameter übergeben werden, z.B. "attr=outdoor&attr=fun". |
|---|---|
| HTTP | GET |
| URL |
http://api.mairdumont.com/data/offer/api/offer/all?lang=de&geocode=,&attr=outdoor&attr=fun http://api.mairdumont.com/data/destination/api/destination/&attr=afoot+cycling |
Die Sortierung erfolgt dreistufig.
Zuerst werden die Treffer in zwei Bereiche geteilt. Der erste Bereich enthält die Angebote, die direkt bei den gesuchten Destinationen verlinkt sind. Der zweite Bereich enthält indirekte Treffer. Gibt es zwei Angebote, eins in Stuttgart und eins in Ostfildern, so werden die Angebote ihrer jeweiligen Stadt-Destination zugeordnet, sowie dem Bundesland. Bei der Suche nach der Destination Ostfildern ist das Angebot in Ostfildern ein direkter Treffer, das Angebot in Stuttgart wird indirekt über das Bundesland getroffen. Diese Aufteilung soll sicherstellen, dass die örtlichen Angebote immer Priorität haben, und es uns gleichzeitig ermöglichen, die Suche so weitläufig zu gestalten, dass es immer Treffer gibt.
Die zweiten Stufe der Sortierung wird auf die zwei Bereiche angewendet, und sorgt somit für die Sortierung im Detail. Für diese Sortierung ist der "sort" Parameter relevant. So können die Angebote innerhalb der beiden Bereiche nach Relevanz, Preis, Neuerscheinungen und Distanz sortiert werden.
| Sort-Parameter | Sortierung |
|---|---|
| REL (default) | Die Angebote werden nach Relevanz sortiert. Oft genutzte Angebote werden nach oben sortiert. |
| PRICE | Die Angebote werden nach Preis sortiert. Die günstigsten Angebote werden nach oben sortiert. |
| DIST | Die Angebote werden nach Distanz zum Suchpunkt sortiert. Der Suchpunkt ist entweder der Mittelpunkt der angegebenen Destination, oder der Geocode bei einer Geocode-Anfrage. Diese Sortierung eignet sich besonders für Destinationen ohne eigene Angebote (keine direkten Treffer), da die indirekten Treffer teilweise sehr weit weg vom Suchpunkt sein können. |
| DATE | Die Angebote werden nach Erstellungsdatum sortiert, neue Angebote werden nach oben sortiert. Es gilt das Erstellungsdatum in der API, nicht das Erstellungsdatum beim jeweiligen Partner. |
Die dritte und letzte Stufe kommt zum Tragen, wenn zwei Angebote z.B. den gleichen Preis haben und nach Preis sortiert wurden. Um eine nachvollziehbare Sortierung sicherzustellen, werden die Angebote in der letzten Stufe nach ihrer ID aufsteigend sortiert.
| ID | Name |
|---|---|
| 1 | Konzerte & Musik |
| 2 | Kunst & Kultur |
| 3 | Sport |
| 4 | Nachtleben & Partys |
| 5 | Musical & Show |
| 6 | Freizeit |
| 7 | Festivals |
| 8 | Feste & Märkte |
| 9 | Messen |
| 10 | Führungen & Vorträge |
| 11 | Kurse & Seminare |
| 12 | Wellness & Lifestyle |
| 13 | Kulinarisches |
| 14 | Shopping |
| 15 | Transfer |
| Attribut | Beschreibung |
|---|---|
| outdoor | Outdoor |
| indoor | Indoor |
| families | Familien |
| shopping | Shopping |
| activity | Sport & Aktivitäten |
| party | Feiern |
| fun | Spaß |
| wellness | Wellness |
| culinary | Genuß & Kulinarik |
| culture | Kultur |
| nature | Natur |
| tours | Touren |
| tickets | Tickets |
| winter | Winter |
| water | im Wasser |
| afoot | zu Fuß |
| cycling | mit Rädern |
| animals | mit Tieren |
| motors | mit Motor |
| airborne | in der Luft |
| Partner | User-ID | Channel-ID | Geocode | Dauer | Relevanz/Rating | Anzahl (Stand Testsystem 31.07.2015) | |
|---|---|---|---|---|---|---|---|
| Regiondo | 59 | 47 | Ja | Ja | Ja, Scoring | 5864 | |
| rent-a-guide | 60 | 48 | Nein (Destination-Mapping) | Ja | Nein | 4073 | |
| guiders | 64 | 50 | Ja | Nein, teilweise im Beschreibungstext | Ja, Ranking | 1004 | |
| GetYourGuide | 65 | 51 | Ja | Ja | Ja, Overall-Rating | 9802 | |
| Viator | 66 | 52 | Ja | Ja | Ja, Rating | 16587 |