Dokumentacja XMLGateway portalu Kulturalna.Warszawa.pl Wersja: 10/31.12.2012 Położenie: http://kulturalna.warszawa.pl/gateway/dokumentacja.pdf Autor: DBS Systems www.dbs-systems.pl 1. Wstęp 1.1 Przeznaczenie interfejsu Interfejs XMLGateway służy do pobierania gromadzonych w bazie portalu Kulturalna.Warszawa.pl. Interfejs przeznaczony jest dla twórców innego oprogramowania (w tym witryn internetowych), które korzystać ma z gromadzonych w portalu. Każdy z odbiorców posługiwać się musi przypisanym do niego, unikalnym kluczem autoryzującym. Klucz ustala i przekazuje odbiorcy aktualny administrator portalu (DBS Systems) na polecenie właściciela portalu (Biuro Kultury Urzędu m. st. Warszawy). 1.2 Techniczna realizacja interfejsu Interfejs XMLGateway pozwala pobierać dane z bazy portalu w formie dokumentów XML. Pobranie dokumentów XML odbywa się za pośrednictwem protokołu HTTP(S). Szczegółowa postać adresów służących do pobierania dokumentów XML została opisana w rozdziale 2. Struktura dokumentów XML została opisana w odpowiednich dokumentach. Dokumenty XML przesyłane odbiorcy są cache'owane po stronie portalu i mają 4 godzinny termin ważności. 1.3 Uwagi dotyczące implementacji aplikacji pobierającej dane Zaleca się stosowanie cache'owania pobieranych dokumentów XML po stronie aplikacji odbierającej dane. Proces cache'owania powinien być zrealizowany w sposób uniezależniający poprawność funkcjonowania aplikacji odbierającej dane od możliwych chwilowych problemów w komunikacji pomiędzy portalem, a odbiorcą (odświeżanie cache po walidacji odebranego dokumentu). 2. Pobieranie 2.1 Pobieranie informacji o wydarzeniach z wybranego okresu czasu Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],events,[start_date],[end_date],[locale],[quarter_i d],[limit],[imp],[activity_id].html. http://www.kulturalna.warszawa.pl/xmlgateway,123456789,events,2008-12-01,2008-12- 10,1,0,0,0,0.html http://www.kulturalna.warszawa.pl/gateway/events.xsd
start_date YYYY-MM-DD Data początkowa end_date YYYY-MM-DD Data końcowa quarter_id 3 Id dzielnicy (gdy 0 - dowolna dzielnica) limit 20 Liczba pobieranych wydarzeń (0 - bez ograniczeń) imp 0 Decyduje o uwzględnieniu parametru 'ważne' podczas pobierania wydarzeń: 0 - nie uwzględnia - pobiera wszystkie 1 - pobiera oznaczone jako ważne 2 - pobiera nieoznaczone jako ważne activity_id 0 Id dziedziny kultury wydarzenia (0 - dziedzina kultury nie jest uwzględniana) 2.2 Pobieranie pojedynczego wydarzenia Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],event,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,event,1922,1.html http://www.kulturalna.warszawa.pl/gateway/event.xsd id 1922 Id wydarzenia
2.3 Pobieranie listy dziedzin kultury powiązanych z danym wydarzeniem Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],event_act,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,event_act,1922,1.html http://www.kulturalna.warszawa.pl/gateway/activities.xsd id 1922 Id wydarzenia 2.4 Pobieranie listy form wydarzeń powiązanych z danym wydarzeniem Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],event_form,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,event_form,1922,1.html http://www.kulturalna.warszawa.pl/gateway/forms.xsd id 1922 Id wydarzenia 2.5 Pobieranie wybranego miejsca (lokalizacji) Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],location,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,location,1922,1.html http://www.kulturalna.warszawa.pl/gateway/location.xsd
id 1922 Id lokalizacji 2.6 Pobieranie listy ID wydarzeń w zadanym zakresie dat Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],events_ids,[start_date],[end_date],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,events_ids,2008-12-01,2008-12-10,1.html http://www.kulturalna.warszawa.pl/gateway/events_ids.xsd start_date YYYY-MM-DD Data początkowa end_date YYYY-MM-DD Data końcowa 2.7 Pobieranie listy ID wydarzeń nowszych od zadanego ID Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],events_ids_after,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,events_ids_after,1922,1.html http://www.kulturalna.warszawa.pl/gateway/events_after.xsd id 1922 Id wydarzenia 2.8 Pobieranie listy ID wydarzeń, które zmieniły się od zadanej daty http://www.kulturalna.warszawa.pl/xmlgateway,[key],events_modified_ids,[edit_date],[locale].html
Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,123456789,events_modified_ids,2008-12-10,1.html http://www.kulturalna.warszawa.pl/gateway/events_modified_ids.xsd edit_date YYYY-MM-DD Zadana data 2.9 Pobieranie treści ostatnich wiadomości Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],news,[imp],[limit],[locale],[thematic].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,news,1,5,1,0.html http://www.kulturalna.warszawa.pl/gateway/news.xsd imp 1 Decyduje o uwzględnieniu parametru 'ważne' podczas pobierania wiadomości: 1 - pobiera tylko ważne 0 - pobiera tylko nieważne 2 - pobiera wszystkie limit 5 Liczba zwracanych ostatnich wiadomości locale 1 Kod wersji językowej: thematic 0 Id serwisu tematycznego: 0 - wiadomość pochodzące z głównego portalu (wartość domyślna) 8 - Media zagraniczne 2.10 Pobieranie obrazów wybranej wiadomości http://www.kulturalna.warszawa.pl/xmlgateway,[key],news_images,[id],[locale].html Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,123456789,news_images,1147,1.html http://www.kulturalna.warszawa.pl/gateway/images.xsd
id 1147 Id wiadomości locale 1 Kod wersji językowej: 2.11 Pobieranie wydarzeń przypisanych do danej wiadomości Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],news_events,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,news_events,1147,1.html http://www.kulturalna.warszawa.pl/gateway/events.xsd id 1147 Id wiadomości locale 1 Kod wersji językowej: 2.12 Pobieranie informacji o wydarzeniach z wybranego okresu czasu z serwisu tematycznego Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],portal_events,[start_date],[end_date],[locale],[p ortal_id],[portal_limit],[fill],[limit].html. http://www.kulturalna.warszawa.pl/xmlgateway,123456789,portal_events,2008-12-01,2008-12- 10,1,12,3,1,10.html http://www.kulturalna.warszawa.pl/gateway/events.xsd start_date YYYY-MM-DD Data początkowa end_date YYYY-MM-DD Data końcowa
portal_id 1 Id serwisu tematycznego: 12 WarsawTour 34 Lato w Warszawie 35 Strefa Kibica portal_limit 3 Limit wydarzeń z portalu tematycznego. Wartość domyślna: 30 Uwaga: ograniczenie liczby wydarzeń jest konieczne, dlatego ustawienie wartości 0 spowoduje pobranie wydarzeń w ilości domyślnej. fill 1 Jeżeli równe 1 stosowane jest uzupełnianie zwracanego zestawu wydarzeń o wydarzenia niepowiązane z serwisem tematycznym i ustawione jako ważne. Uzupełnienie występuje jeżeli: 'portal_limit' < 'limit lub 'liczba_wyd_z_serwisu' < 'portal_limit' limit 10 Limit zwracanych wydarzeń. Patrz też opis parametru 'portal_limit'. Oddziałuje tylko wtedy, gdy parametr 'fill' ma wartość 1. Wartość domyślna: 30 2.13 Pobieranie filmów z Platformy Audiowizualnej Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],videos,[id],[code],[event_id],[person_id],[inst_i d],[news_id],[portal_id],[act_id],[form_id],[tag],[q],[above_id].html. http://www.kulturalna.warszawa.pl/xmlgateway,123456789,videos,,rwobsbp4iz4,,,,,,,,,,.html http://www.kulturalna.warszawa.pl/gateway/videos.xsd id code event_id Id filmu w bazie platformy audiowizualnej Identyfikator filmu w serwisie YouTube Id wydarzenia. Jeżeli niepuste, zwracane są filmy powiązane z danym wydarzeniem
person_id inst_id news_id portal_id act_id form_id tag q above_id Id osoby. Jeżeli niepuste, zwracane są filmy powiązane z daną osobą Id instytucji. Jeżeli niepuste, zwracane są filmy powiązane z daną instytucją Id wiadomości. Jeżeli niepuste, zwracane są filmy powiązane z daną wiadomością Id portalu tematycznego. Jeżeli niepuste, zwracane są filmy powiązane z danym serwisem tematycznym Id dziedziny kultury. Jeżeli niepuste, zwracane są filmy powiązane z daną dziedziną kultury Id formy wydarzenia. Jeżeli niepuste, zwracane są filmy powiązane z daną formą wydarzenia Tag. Jeżeli podano, zwracane są filmy powiązane z danym tagiem Szukana fraza. Jeżeli niepuste, zwracane są filmy, w których nazwie lub tagu występuje dana fraza Id progowe. Jeżeli podane, zwracane są filmy nowsze od filmu o podanym id 2.14 Pobieranie informacji o wydarzeniach na potrzeby serwisu mobilnego Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],mobile_events,[start_date],[end_date],[locale],[ activity_id],[query],[num],[start].html. http://www.kulturalna.warszawa.pl/xmlgateway,123456789,mobile_events,2008-12-01,2008-12- 10,1,2,spotkanie,10,0.html http://www.kulturalna.warszawa.pl/gateway/events_mobile.xsd start_date YYYY-MM-DD Data początkowa end_date YYYY-MM-DD Data końcowa activity_id 1 Id dziedziny kultury query wyszukiwana fraza ( encoding) num 10 Liczba zwracanych wydarzeń (na potrzeby stronicowania) start 0 Numer pozycji od której wydarzenia mają być
zwracane (na potrzeby stronicowania) 2.15 Pobieranie listy dziedzin kultury Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],activities,[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,activities,1.html http://www.kulturalna.warszawa.pl/gateway/activities.xsd 2.16 Pobranie listy wydarzeń podrzędnych danego wydarzenia Przykładowy http://www.kulturalna.warszawa.pl/xmlgateway,[key],sub_events,[id],[locale].html http://www.kulturalna.warszawa.pl/xmlgateway,123456789,sub_events,1922,1.html http://www.kulturalna.warszawa.pl/gateway/subevent.xsd id 1922 Id wydarzenia nadrzędnego