api.orange.pl/locateterminal tutorial dla budujacych aplikacje lokalizacyjne (i nie tylko) wer. 1.1 Grzegorz Sabak, Orange Polska, SiPU październik 2012
Spis treści Spis treści 1 Intro 2 api.orange.pl Wprowadzenie Przykład - przegladarka Przykład - Python 2 i 3 Przykład - PHP Przykład - Java 3 Integracja WWW WordPress Krok po kroku Plugin Lemon Mini W stronę klienta: JavaScript 4 Lokalizacja w sieci Orange Informacje podstawowe Dokładność lokalizacji 5 Zakończenie
Intro O tutorialu... Ten przewodnik przeznaczony jest dla osób, które chca rozpoczać korzystanie z API telekomunikacyjnego udostępnianego (obecnie testowo przez Orange Polska). Zawiera przykłady kodu źródłowego w różnych językach programowania, które moga być wykorzystanie do testowania swojego środowiska, badź jako ziarno na bazie którego zbudowana zostanie większa funkcjonalność. Pożyteczne techniki/narzędzia/protokoły Aby efektywnie skorzystać z tego przewodnika potrzebna jest podstawowa znajomość takich języków programowania jak Java, Perl i PHP (nieznajacy któregoś z nich moga pominać pewne fragmenty). Dodatkowo, w trakcie czytania tutoriala warto uzupełnić swoja wiedzę w następujacych tematach (pod logami sa linki do stron domowych projektów): - Ajax -pozwala na asynchroniczne uzupełnienie zawartości strony WWW, - jquery - biblioteka JavaScript, - geojson - format kodowania obiektów GIS jako obiektów JSON, - Firebug - dodatek do Firefoxa wspierajacy development dla Internetu, - WampServer - Apache, PHP, MySQL na Windowsie, - WordPress - oprogramowanie do publikacji w Internecie, - Eclipse - zintegrowane środowisko programistyczne.
api.orange.pl 1 Intro 2 api.orange.pl Wprowadzenie Przykład - przegladarka Przykład - Python 2 i 3 Przykład - PHP Przykład - Java 3 Integracja WWW WordPress Krok po kroku Plugin Lemon Mini W stronę klienta: JavaScript 4 Lokalizacja w sieci Orange Informacje podstawowe Dokładność lokalizacji 5 Zakończenie
api.orange.pl Wprowadzenie Wprowadzenie api.orange.pl - portal informacyjny portal poświęcony Telecom Web Services w sieci Orange Polska informacje umożliwiajace szybki start dokumentacja i FAQ udostępnione usługi: SMS, USSD, lokalizacja przykłady aplikacji hasło dostępu: przydzielane indywidualnie api.orange.pl - API do usług telco URL do wywoływania usług telekomunikacyjnych Komunikacja szyfrowana z autoryzacja HTTP Basic bezpłatne (na chwilę obecna) bezpieczne dla abonentów sieci Orange w fazie testów - nie wszystko zawsze działa hasło dostępu: uzyskuje się wysyłajac SMSa o treści: API na numer 551
api.orange.pl Przykład - przegladarka Przykłady Korzystanie z API - przykłady W przedstawionych przykładach należy wprost w kodzie źródłowym zastapić wartościami następujace ciagi znaków: API_USER - indywidualny login użytkownika API, najczęściej w postaci 48501XXXXXX. API_PASSWORD - hasło (coś w rodzaju D873MFO0QEDF56E), API_MSISDN - nr tel. dla którego wywoływana jest funkcja API (np. lokalizowanego terminala) w postaci 501YYYYYY. Korzystanie z API przez przegladarkę WWW 1 W oknie przegladarki wpisujemy: https://api.orange.pl/sendussd/?to=api_msisdn&msg=orange+api+rules+ok 2 Serwer pyta o autoryzację. Podajemy w odpowiednich polach API_USER i API_PASSWORD 3 Użytkownik o numerze telefonu API_MSISDN otrzymuje ciekawe hasło. 4 W oknie przegladarki widzimy potwierdzenie przyjęcia wiadomości przez serwer: 1 <?xml version="1.0" encoding="utf-8"?> 2 <response> 3 <result>4f423e1d6978c683799495</result> 4 <deliverystatus>messagewaiting</deliverystatus> 5 </response>
api.orange.pl Przykład - Python 2 i 3 Przykład - Python 2 Korzystanie z API w skryptach Python 2 Poniżej przedstawiono przykładowy kod źródłowy w języku Python wysyłajacy zapytanie o lokalizację terminala. Plik jest również załaczony tutaj: orangeapi2.py 1 from base64 import b64encode 2 from httplib import HTTPSConnection 3 4 import urllib 5 6 #dane uzytkownika API 7 apiusr = b"api_user" 8 apipwd = b"api_password" 9 10 #parametry wywolania API 11 params_loc = urllib.urlencode({ msisdn : API_MSISDN}) 12 params_msg = urllib.urlencode({ msg : Orange API rules OK, to : API_MSISDN}) 13 14 #zapytanie do serwera 15 userpasswd = b64encode(apiusr+b":"+apipwd).decode("ascii") 16 headers = { Authorization : Basic %s % userpasswd } 17 18 conn = HTTPSConnection("api.orange.pl") 19 conn.request( GET, /terminallocation? +params_loc, headers = headers) 20 #conn.request( GET, /sendussd? +params_msg, headers = headers) 21 #conn.request( GET, /sendsms? +params_msg, headers = headers) 22 23 #analiza odpowiedzi z serwera 24 response = conn.getresponse() 25 print(response.status, response.reason) 26 print() 27 data = response.read() 28 print(data) 29 conn.close()
api.orange.pl Przykład - Python 2 i 3 Przykład - Python 3 Korzystanie z API w skryptach Python 3 W wersji trzeciej Pythona wszystko jest tak samo, tylko umieszczone w innych modułach :) Plik źródłowy jest również załaczony tutaj: orangeapi3.py 1 from http.client import HTTPSConnection 2 from base64 import b64encode 3 4 import urllib.parse 5 6 #dane uzytkownika API 7 apiusr = b"api_user" 8 apipwd = b"api_password" 9 10 #parametry wywolania API 11 params_loc = urllib.parse.urlencode({ msisdn : API_MSISDN}) 12 params_msg = urllib.parse.urlencode({ msg : Orange API rules OK, to : API_MSISDN}) 13 14 #zapytanie do serwera 15 userpasswd = b64encode(apiusr+b":"+apipwd).decode("ascii") 16 headers = { Authorization : Basic %s % userpasswd } 17 18 conn = HTTPSConnection("api.orange.pl") 19 conn.request( GET, /terminallocation? +params_loc, headers = headers) 20 #conn.request( GET, /sendussd? +params_msg, headers = headers) 21 #conn.request( GET, /sendsms? +params_msg, headers = headers) 22 23 #analiza odpowiedzi z serwera 24 response = conn.getresponse() 25 print(response.status, response.reason) 26 print() 27 data = response.read() 28 print(data) 29 conn.close()
api.orange.pl Przykład - PHP Przykład - PHP Korzystanie z API w skryptach PHP Jak można zauważyć PHP jest również dość kompaktowe w porównaniu do następnego przykładu w Javie :) Plik źródłowy jest również załaczony tutaj: orangeapi.php 1 <?php 2 //dane uzytkownika API 3 $username = API_USER ; 4 $password = API_PASSWORD ; 5 6 //parametry wywolania API 7 $params_loc = array( msisdn => API_MSISDN ); 8 9 $params_msg = array( to => API_MSISDN, 10 msg => Orange API rules OK ); 11 12 $url = https://api.orange.pl/terminallocation?. http_build_query($params_loc); 13 //$url = https://api.orange.pl/sendussd?. http_build_query($params_msg); 14 15 $context = stream_context_create(array( 16 http => array( 17 header => "Authorization: Basic ". base64_encode("$username:$password") 18 ) 19 )); 20 21 //zapytanie do serwera 22 $page = file($url, false, $context); 23 24 //odpowied z serwera 25 foreach ($page as $part) 26 { 27 echo $part; 28 } 29?>
api.orange.pl Przykład - Java Przykład - Java Korzystanie z API w języku Java W załaczniku przedstawiono przykładowy kod źródłowy w języku Java wysyłajacy krótki tekst jako wiadomość USSD. Przed kompilacja pliku należy dociagn ać biblioteki httpclient w wersji 4.1 będace częścia Apache HttpComponents. Przejście przez proxy Jeśli połaczenie do api.orange.pl wymaga przejścia przez proxy, w kodzie należy umieścić następujace linie: 1 HttpHost proxy = new HttpHost("http.proxy.com", 8080, "http"); 2 httpclient.getparams().setparameter(connroutepnames.default_proxy, proxy); Zaminiajac oczywiście nazwę hosta (powyżej http.proxy.com) i numer portu (8080) na właściwe. Dla użytkowników maven a Programiści korzystajacy z pakietu maven moga dociagn ać właściwa wersję httpclient a poprzez dodanie do pliku pom.xml następujacej definicji zależności: 1 <dependency> 2 <groupid>org.apache.httpcomponents</groupid> 3 <artifactid>httpclient</artifactid> 4 <version>4.1.3</version> 5 <scope>compile</scope> 6 </dependency>
Integracja WWW 1 Intro 2 api.orange.pl Wprowadzenie Przykład - przegladarka Przykład - Python 2 i 3 Przykład - PHP Przykład - Java 3 Integracja WWW WordPress Krok po kroku Plugin Lemon Mini W stronę klienta: JavaScript 4 Lokalizacja w sieci Orange Informacje podstawowe Dokładność lokalizacji 5 Zakończenie
Integracja WWW WordPress Integracja WordPress Korzyści z integracji strony WWW z siecia komunikacyjna Większa interaktywość = większy ruch Bezpieczeństwo Nowe konteksty np. lokalizacja Telekomunikacyjne wsparcie procesów biznesowych Jednym ze sposobów integracji jest przygotowanie plugina dla oprogramowania WordPress. Czym jest WordPress i dlaczego warto go używać? Najpopularniejszy silnik blogowy wybierany przez małych i największych (CNN, NYTimes, Nokia, TechCrunch, People, WordPress.com, blog.pl (Onet)) Napisany w PHP, oparty na MySQL, wykorzystuje CSS3 i JavaScript (jquery) Łatwo modyfikowalny wyglad (motywy) i funkcjonalność (plug-iny) 21k+ gotowych pluginów w oficjalnym repozytorium (darmowych) 1.6k+ gotowych motywów (również darmowych) Łatwa instalacja i aktualizacja, przyjazna administracja Aktywnie rozwijany przez społeczność developerów Architektura przyjazna dostosowywaniu: API, szablony, zaczepy: (akcje i filtry) Bezpieczeństwo: czyszczenie danych, role użytkowników, prawa dostępu do treści
Integracja WWW Krok po kroku 1. Przygotowanie środowiska 1 Zainstaluj WAMP - zawiera Apache, MySql 2 Zainstaluj WordPress - aktualna wersja do ściagnięcia ze strony projektu 3 Zainstaluj Eclipse lub dowolne inne zintegrowane środowisko deweloperskie wspierajace PHP 2. Praca za PROXY Jeśli PC na którym zainstalowane jest środowisko znajduje się za proxy HTTP, to w pliku wp-config.php znajdujacym się w głównym katalogu instalacji WordPressa należy dodać następujacy kod - podstawiajac odpowiednie wartości. define( WP_PROXY_HOST, adres.ip.proxy ); define( WP_PROXY_PORT, 8080 ); 3. Instalacja pluginu 1 Utwórz katalog wp-content/plugins/lemon-mini 2 Umieść w tym katalogu plik lemon-mini.php (z załacznika ) 3 Aktywuj plugin w konsoli WordPress
Integracja WWW Krok po kroku Integracja WordPress lemon-mini Lemon Mini to plugin dla WordPressa, którego główne funkcjonalności to: Zamienianie w treści wpisu słowa kluczowego [lmini-locate msisdn="" user="" passwd=""/] na tekst informujacy o lokalizacji. Argumenty: msisdn - lokalizowany numer, user - użytkownik api.orange.pl, passwd - hasło użytkownika. Udostępnianie filtra lmini-locate, który może być wykorzystywany przez inne rozszerzenia WordPressa. Uzyskana lokalizacja przechowywane jest przez 60 sekund. Po tym czasie każde odświeżenie strony powoduje wywołanie API do lokalizacji terminala. Więcej informacji na temat plugina oraz jego najbardziej aktualna wersję można pobrać ze strony telco21.pl. telco21.pl telco21.pl jest strona dedykowana koncepcji Telco 2.1, polegajacej na dalszym uproszczeniu sposobów korzystania z funkcjonalności telekomunikacyjnych udostępnianych przez operatorów sieci. Na stronie umieszczony dostępna jest zawsze najnowsza wersja plugina.
Integracja WWW Krok po kroku plugin-mini.php Kod źródłowy plugina znajduje się w załaczniku. Warto zwrócić uwagę na jego kilka poniższych fragmentów. Rejestracja filtra lmini-locate. 29 add_filter( lmini-locate, lmn_localize, 10, 3 ); Po wywołaniu funkcji apply_filters( lmini-locate, $msisdn, $user, $passwd ) zostanie wywołana funkcja lmn_localize(), do której przekazane zostana trzy argumenty. Rejestracja shortcode u lmini-locate. 32 add_shortcode( lmini-locate, lmn_shortcode_handler ); Jeśli w treści posta pojawi się słowo kluczowe [lmini-locate /], to zostanie ono zamienione na wartość tekstowa zwrócona przez funkcję lmn_shortcode_handler(). Zakodowanie nazwy użytkownika i hasła: Funkcja base64_encode(). 40 $usrpwd = base64_encode( "{$options[ user ]}:{$options[ passwd ]}" ); Zapamiętanie lokalizacji na 60 sekund w celu zmniejszenia liczby odwołań do API. Użycie funkcji: get_transient(), set_transient(). 75 $loc = get_transient( lmn_location_. $msisdn ); 76 77 if ( $temp_loc ) 78 return $loc; 79 else { 80 $loc = lmn_call_orange_api( $options, terminallocation, $query ); 81 82 // zapamietaj lokalizacje przez 60 sek. 83 set_transient( lmn_location_. $msisdn, $loc, 60 ); 84 }
Integracja WWW W stronę klienta: JavaScript JavaScript Programowanie dla browsera Często zachodzi potrzeba/chęć/konieczność by o lokalizację abonenta wystapić z poziomu skryptu wykonywanego prze przegladarkę. W takim przypadku należy zwrócić uwagę na dwie rzeczy: Wywołanie API lokalizacyjnego pod czas generowania kodu HTML opóźni moment wyświetlenia strony o jakieś 4-5 sek. potrzebne na zlokalizowanie terminala. Obowiazuje same origin policy, czyli zasada, która mówi, że skrypt wykonywany przez przegladarkę może łaczyć się jedynie z serwerem, z którego został pobrany. Problem pierwszy można rozwiazać korzystajac z Ajaxa, co pozwoli na wyświetlenie strony i asynchroniczne uzupełnienie jej po wykonaniu lokalizacji. Jednym z rozwiazań drugiej kwestii jest wykorzystanie niewielkiego skryptu umieszczonego na serwerze, który będzie pełnił pożyteczna rolę proxy i dodatkowo przekonwertuje otrzymanego XML-a na obiekt GeoJSON. To rozwiazanie zostało opisane na następnych slajdach. Przykłady bardziej zaawansowanych zastosowań i innych podejść do rozwiazania powyższych kwestii zamieszczono na blogu telco21.pl.
Integracja WWW W stronę klienta: JavaScript lmini.json.php 1 <?php 2 require_once(../../../wp-load.php ); 3 4 header( Cache-Control: no-cache, must-revalidate ); // HTTP/1.1 5 header( Content-Type: application/json ); 6 7 parse_str($_server[ QUERY_STRING ], $query); 8 9 define( API_USER, ); // tu wpisz nazwe uzytkownika 10 define( API_PASSWORD, ); // tu wpisz haslo 11 12 $loc = apply_filters( lmini-locate, $query[ msisdn ], API_USER, API_PASSWORD ); 13 14 $response = array(); 15 $response[ type ] = FeatureCollection ; 16 $response[ features ] = array(); 17 $response[ features ][]= array( 18 type => Feature, 19 geometry => array( 20 type => Point, 21 coordinates => array( 22 floatval( $loc[ longitude ] ), 23 floatval( $loc[ latitude ] ), 24 ) 25 ), 26 properties => array( 27 timestamp =>$loc[ timestamp ], 28 ) 29 30 ); 31 echo json_encode( $response ); 32?> Komentarz Skrypt wywołuje zdefiniowany w pluginie lemon-mini filtr lmoni-locate, który zwraca lokalizację abonenta. Następnie przygotowuje tablicę zgodna ze specyfikacja GeoJSON, która funkcja PHP json_encode() koduje tablicę do obiektu JSON.
Integracja WWW W stronę klienta: JavaScript locate.html 1 <!DOCTYPE HTML> 2 <html> 3 <head> 4 <meta charset="utf-8"> 5 <title>localizacja przy pomocy api.orange.pl</title> 6 <style type="text/css"> 7.in-progress { 8 font-style: italic; 9 } 10 </style> 11 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script> 12 <script> 13 $(document).ready(function(){ 14 $.getjson( lmini.json.php, 15 {msisdn: } // tu wpisz lokalizaowny numer 16 ).done (function ( data ){ 17 var msg = "Zlokalizowano: " + data.features[0].geometry.coordinates[0] + 18 "," + data.features[0].geometry.coordinates[1]; 19 $( #location ).text(msg).removeclass( in-progress ); 20 }); 21 }); 22 </script> 23 </head> 24 <body> 25 <span id="location" class="in-progress">location in progress...</span> 26 </body> 27 </html> Komentarz Strona korzysta z biblioteki jquery. Po wyświetleniu zawartości strony następuje asynchroniczne odwołanie w tle do serwera (skrypt lmini.json.php). Otrzymany w odpowiedzi obiekt JSON jest dekodowany, a na podstawie otrzymanych danych uaktualniana jest zawartość strony (bez konieczności jej odświeżenia).
Lokalizacja w sieci Orange 1 Intro 2 api.orange.pl Wprowadzenie Przykład - przegladarka Przykład - Python 2 i 3 Przykład - PHP Przykład - Java 3 Integracja WWW WordPress Krok po kroku Plugin Lemon Mini W stronę klienta: JavaScript 4 Lokalizacja w sieci Orange Informacje podstawowe Dokładność lokalizacji 5 Zakończenie
Lokalizacja w sieci Orange Informacje podstawowe Wprowadzenie Podstawowe informacje Terminal mobilny: urzadzenie użytkownika + karta SIM, komórka: obszar zasięgu radiowego. W sieci Orange lokalizacja terminali wykonywana jest metoda Cell-Id - jako lokalizacja zwracany jest punkt przypisany identyfikatorowi komórki. Środek komórki: punkt zwracany jako lokalizacja terminala znajdujacego się w komórce - oznaczany pomarańczowym trójkatem na prezentowanych mapkach. Komórki pokrywaja się, w wybrane miejsce może należeć do wielu komórek sieci telefonii mobilnej. Dokładność lokalizacji zależy od typu obszaru, na którym znajduje się terminal. Dokładność lokalizacji zależy od tego czy terminal jest w sieci 2G (większa) czy 3G (mniejsza). Informacja o lokalizacji zwracana jest po ok 4-5 sekundach od zapytania.
Lokalizacja w sieci Orange Informacje podstawowe Wprowadzenie Problemy praktyczne z wykorzystaniem lokalizacji Relatywnie duży (w stosunku do systemu GPS) bład lokalizacji - więcej informacji na następnych slajdach Przy wielokrotnej lokalizacji nieporuszajacego się terminala moga być zwracane jego różne lokalizacje (pozorny ruch terminala). Bardziej zaawansowane telefony (działajace w sieci 3G) będa lokalizowane z większym błędem niż te mniej zaawansowane. Nie można zakładać, że jako lokalizacja terminala wskazany zostanie środek komórki najbliższy rzeczywistemu położeniu terminala. Współrzędne środków komórek sa "poprawiane" przez operatora sieci - z czasem zmieniaja swoje położenie. Położenie środków komórek Na następnych slajdach przedstawiono mapki, na których pomarańczowymi trójk atami zaznaczono środki komórek na obszarach w pobliżu wybranych lokalizacji.
Lokalizacja w sieci Orange Informacje podstawowe Okolice PW EiTI
Lokalizacja w sieci Orange Informacje podstawowe Okolice Orange Labs
Lokalizacja w sieci Orange Informacje podstawowe Okolice UWM
Lokalizacja w sieci Orange Informacje podstawowe Okolice PŁ
Lokalizacja w sieci Orange Dokładność lokalizacji Dokładność lokalizacji Wprowadzenie Poniżej przedstawiono (za [5]) wyniki testów dokładności lokalizacji w sieci komórkowej Orange przeprowadzonych w latach 2010-2011. Jako bład lokalizacji przyjmuje się odległość od punktu wskazanego przez odbiornik GPS do punktu wskazanego przez usługę lokalizacji terminala w sieci komórkowej. Typy analizowanych obszarów i dróg highway- fragmenty autostrad major- drogi ekspresowe, drogi krajowe regular- drogi inne: wojewódzkie, powiatowe, itp. city- obszary ścisłych centrów miast town- obszary małych miast, duże miasta poza ścisłym centrum rural- obszary pozamiejskie
Lokalizacja w sieci Orange Dokładność lokalizacji Bład lokalizacji Statystyki błędu lokalizacji - wartości w km typ obiektu n ē σ Q 25 Q 50 Q 75 e max Q 75 Q 25 highway 3801 2.63 1.93 1.17 2.24 3.60 20.37 2.43 major 13147 2.00 1.58 0.83 1.54 2.79 10.46 1.97 regular 6889 3.73 2.47 2.06 3.30 4.74 28.83 2.70 city 729 0.38 0.31 0.17 0.31 0.49 1.62 0.32 town 2482 1.16 1.00 0.47 0.86 1.50 7.77 1.03 rural 6044 3.66 1.90 2.42 3.39 4.61 17.53 2.19 Analiza Na podstawie uzyskanych wyników można wywnioskować, że dokładność metody Cell-Id jest największa dla obszarów typu city. Bład lokalizacji dla 25% przypadków był mniejszy niż 0.17 km, a dla 75% mniejszy niż 0.49 km. Dużo gorszej dokładności lokalizacji metoda Cell-Id należy spodziewać się dla dróg typu regular i obszarów typu rural. Bład średni lokalizacji wynosi dla nich odpowiednio 3.47 km i 3.67 km. Sa to wartości kilkukrotnie większe niż wartość błędu średniego dla obszaru city. Potwierdza to powszechne przekonanie, że w centrach miast operatorzy telefonii komórkowej buduja znacznie więcej komórek o mniejszym zasięgu, by w ten sposób zaspokoić istniejac a tam potrzebę większej pojemności sieci wynikajac a z koncentracji ludności. Należy zauważyć, że dla wszystkich typów dróg i obszarów stosunek odchylenia standardowego do wartości średniej jest powyżej 50%, a w przypadku city wynosi 93.2%. Świadczy to o dużym rozproszeniu wartości błędu. Porównujac jednak wartości rozstępów międzykwartylowych (kolumna Q 75 Q 25 ), można zauważyć, że wartość dla dróg typu regular jest kilkukrotnie większa niż dla obszarów typu city. Oznacza to, że rozkład błędu dla dużych miast jest znacznie mniej rozproszony niż dla dróg wojewódzkich.
Lokalizacja w sieci Orange Dokładność lokalizacji Statystyki błędu lokalizacji - histogramy częstości 0.35 0.30 0.25 0.20 0.15 0.10 0.05 0.00 0.35 0.30 0.25 0.20 0.15 0.10 0.05 0.00 0 2 4 6 8 10 error [km] city town rural 0 2 4 6 8 10 error [km] highway major regular
Zakończenie Historia dokumentu data wer. autor opis 02.2012 1.0 Grzegorz Sabak wersja poczatkowa (PHP, Python, dokładność lokalizacji) 10.2012 1.1 Grzegorz Sabak dodano opis pluginu dla WordPress, korzystanie z JavaScript, Ajax, GeoJSON Odnośniki Strona główna api.orange.pl http://api.orange.pl Oficjalna strona domowa Pythona http://www.python.org Oficjalna strona domowa PHP http://www.php.net Strona domowa WordPress http://www.wordpress.org/ [5] G. Sabak. Modelowanie lokalizacji użytkowników sieci telefonii komórkowej dla potrzeb Inteligentnych Systemów Transportowych. Wojskowa Akademia Techniczna, 2011. Wersja PDF
Zakończenie Zamiast zakończenia