ITI0011:Säuts (2014)

Allikas: Kursused
Mine navigeerimisribale Mine otsikasti

Tagasi ITI0011 lehele.

Üldine

Ülesande tekst on poolik (ehk siis detailid võivad veel muutuda)!

Tähtaeg: 21. või 23. oktoober (vastavalt rühma tunnile)
Enne seda nädalat esitamine annab +1 lisapunkti.

Ülesande eesmärk on luua interaktiivne programm, millega saab hallata avalikke säutse (i.k. tweets)

Programmi funktsionaalsus:

  • programmi käivitamisel on võimalik kogu funktsionaalsust juhtida käsurea parameetritega (nt. java Twitter -location Tallinn -c 40 -w tweets.txt)
  • kui programm käivitatakse ilma käsurea parameetriteta, avaneb interaktiivne keskkond, kuhu saab käske kirjutada
  • programmil peab olema loetav juhis (nii käsurealt käivitades kui ka interaktiivses keskkonnas)
  • kasutaja saab sisestada asukoha nimetuse (võib olla linn, objekti nimi vms), programm leiab viimased avalikud säutsud, mis on selle objekti või linna läheduses tehtud
  • programm võimaldab määrata, mitu säutsu tulemuses väljastatakse
  • programm võimaldab tulemuse faili kirjutada
  • programm võimaldab juba alla tõmmatud tulemused failist lugeda
  • programm võimaldab tulemusi sorteerida ettemääratud parameetri järgi

Põhiosa - 5p

Teie programm teeb päringu sotsiaalvõrgustiku Twitter avalike säutsude (tweet) seast. Päritakse viimased avalikud säutsud vastavalt etteantud kohanimele ja kuvatakse need kasutajale.

Funktsionaalsus:

  • loetakse etteantud kohanimi (nt Tallinn)
  • kohanime kohta päritakse tema geograafilised koordinaadid (latitude, longitude)
  • saadud geograafilisi koordinaate kasutatakse, et arvutada välja säutsude kogumise keskpunkt ja otsitava ala raadius
  • Twitteri API-sse saadetakse päring vastavalt määratud keskpunkti ja raadiusega
  • Twitteri API vastusest loetakse välja vajalikud andmed ja kuvatakse ekraanile.
  • programmile saab kohanime ette anda kas käsurealt või programmi käivitamisel küsib programm asukohta

Kohanimele vastavad koordinaadid

Kasutame OpenStreetMap kommuuni tööriista Nominatim (Nominatim wiki leht). Te saadate sellele tööriistale päringu soovitud kohanimega ja vastusest loete välja kohanimele vastava piirkonna ümbritseva ala piirmised punktid (bounding box).

Näitepäring: http://nominatim.openstreetmap.org/search?q=Tallinn&format=xml

Sealt saate tulemuse (kompaktsuse mõttes on näidatud vaid olulisem osa tulemusest): 

<searchresults timestamp="Sat, 13 Sep 14 21:47:21 +0000" 
attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright" 
querystring="Tallinn" polygon="false" 
exclude_place_ids="98174326,11438224,6000303521,6919504,6893196,86869124,15103978,5983246058" 
more_url="http://nominatim.openstreetmap.org/search?format=xml&
exclude_place_ids=98174326,11438224,6000303521,6919504,6893196,86869124,15103978,5983246058&accept-language=en-
US,en;q=0.5&q=Tallinn">
<place place_id="98174326" osm_type="relation" osm_id="2164745" place_rank="16" 
boundingbox="59.351806640625,59.5915794372559,24.5501689910889,24.9262847900391" lat="59.4372155" 
lon="24.7453688" display_name="Tallinn, Harju maakond, Estonia" class="place" type="city" 
importance="0.7819722223575" icon="http://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png"/>
...
</searchresults>

Tulemuseks saate mitu erinevat kohta, mille nimi on Tallinn (või nimes sisaldub selline sõna). Kõige esimene vaste meie programmi jaoks sobib. Seega loete välja esimese "place" elemendi. Kuna Twitteri päringu jaoks on meil vaja koordinaati ning raadiust (kui suure ala pealt tulemusi otsitakse), siis huvitavad meid atribuudid "lat" ja "lon" (latitude ja longitude), mis määravad ära keskpunkti, ning atribuut "boundingbox", mis näitab antud asukoha ümbritseva ala piirjooni. Antud näite näite puhul lat="59.4372155", lon="24.7453688", boundingbox="59.351806640625,59.5915794372559,24.5501689910889,24.9262847900391".

Twitteri päringus otsitav piirkond on märgitud keskpunkti ning raadiusega. Keskpunktiks võib kasutada otse eelnevalt saadud "lat" ja "lon" väärtusi. Raadiuse leidmiseks võib kasutada "boundingbox" väärtust. Kuna raadius peab olema esitatud näiteks kilomeetrites, siis tuleks boundingbox argumentide järgi leida mõistlik raadius. Tähelepanu, erinevas maakera piirkonnas on näiteks latitude 0.1 ühikuline erinevus oluliselt erineva pikkusega. Antud ülesande jaoks ei pea te arvutama väga täpse raadiuse, mis piiratud alasse sisse jääb. Piisab, kui te suurusjärgu panete paika. Siin ülesande kirjelduses konkreetset valemit või näidet toodud ei ole - selle võrra tulevad loodetavasti esitatud kodused ülesanded võimalikult erinevad. Väga täpseks ja põhjalikuks ei tasu ka minna - boonuspunkte selle arvutuse eest üldjuhul ei saa.

Seega teil on oluline, et oskate vajalikud andmed välja lugeda ning need teisendada keskpunktiks ja raadiuseks.

Märkus. Põhiosa lahendamiseks sobib ka see, kui kasutate mõnda muud API-t (näiteks Google Maps'i oma).

Twitteri API

Twitteri API (https://dev.twitter.com/docs/api/1.1) võimaldab programmiga teha automaatseid päringuid sotsiaalvõrgustiku Twitter andmetest. Antud ülesande lahendamiseks ei pea te olema aktiivne Twitteri kasutaja.

Twitteri API kasutamiseks on teil vajalik siiski luua konto ning selle alla App (application). Kui olete twitteri konto teinud ja sisse loginud, peaksite nägema oma rakendusi sellelt lehelt: https://apps.twitter.com/ (link on olemas ka dev.twitter.com veebilehe lõpus "TOOLS" nimekirja all). Seal looge oma app, kus võite veebileheks panna suvalise URL-i (kasvõi kursuse veebilehe).

Kui olete oma rakenduse loonud, näete seda oma applications nimekirjas. Kui avate loodud rakenduse, siis "API keys" tääbi alt avanevad rakenduse seaded. Sealt huvitavad meid "API key" ja "API secret". Neid kahte väärtust on vaja, et teha päringuid Twitter API-st.

Päring ise, mida peab kasutama, on kirjeldatud siin: https://dev.twitter.com/rest/public/search ja https://dev.twitter.com/rest/reference/get/search/tweets

Näiteks võiks päring olla selline: https://api.twitter.com/1.1/search/tweets.json?q=&geocode=59.437215524.7453688,1km&result_type=recent

Mainitud link brauseris ei peagi tulemust andma, kuna te pole eelnevalt sisse loginud. See annab Tallinnas säutse 1km raadiuses.

Natuke informatsiooni, kuidas rakendust vastu Twitteri API-t autentida: https://dev.twitter.com/oauth .

Selleks, et kogu protsess ei oleks liiga töömahukas ja keeruline, soovitame antud ülesande jaoks kasutada mõnda teeki (library), mis oskab autentimise ja ka pärimise teie eest ära teha. Üks selline, mille kohta on allpool ka paar koodinäidet, on siin: http://twitter4j.org/ . Kui tahate ja oskate, võite kasutada ka mõnda muud.

twitter4j puhul on teil vaja kätte saada järgmine fail: twitter4j-core-4.0.2.jar . Kui tõmbate alla zip-formaadis arhiivi, paikneb see fail kaustas "lib". Kirjutamise hetkel oli kasutusel versioon 4.0.2, see võib vabalt muutuda - vastavalt on siis ka failinimi erinev. Selle jar-faili peate oma Eclipse'i projekti lisama: project properties > java build path > libraries tääb > add external jars ... ning otsite üles nimetatud faili.

Konfigureerimise üks võimalus on selline: 

		ConfigurationBuilder cb = new ConfigurationBuilder();
		cb.setDebugEnabled(true)
		.setApplicationOnlyAuthEnabled(true);
		cb.setOAuthConsumerKey(TWITTER_CUSTOMER_KEY)
		  .setOAuthConsumerSecret(TWITTER_CUSTOMER_SECRET);
		
		TwitterFactory tf = new TwitterFactory(cb.build());
		twitter4j.Twitter twitter = tf.getInstance();
		
		OAuth2Token token;
		try {
			token = twitter.getOAuth2Token();
		} catch (TwitterException e1) {
			// TODO Auto-generated catch block
			e1.printStackTrace();
		}

Üleval näites TWITTER_CUSTOMER_KEY ja TWITTER_CUSTOMER_SECRET on konstandid ja nende väärtused on võetud twitteri lehel loodud rakenduse lehelt (application key ja application secret vastavalt). Loomulikult võite seadistamise teha ka konfiguratsioonifailiga või muudmoodi (selle kohta leiate rohkem infot teegi kodulehelt).

Seda, kuidas nüüd teegiga vajalik päring teha, peate ise uurima. Aga selle kohta on veebilehel olemas ka paar näidet.

Kui teil on Twitteri konto olemas, saate olemasoleva konto alla luua rakenduse. Kuigi üldiselt on ülesande eesmärk pärida avalikke säutse, võite teha rakenduse, mis pärib teie kasutajaga seotud säutse (ehk siis nende omasid, keda jälgite ja/või kes on sõbrad). Jällegi, üldjuhul see lisapunkte ei anna. Tähelepanu, kui teete päringuid oma sõbrade kohta, on teil lisaks rakenduse võtmele lisada juurde ka teie enda võtmed. Selle kohta leiate näiteid siit: http://twitter4j.org/en/configuration.html . Kõik sealsed näited käivadki selle olukorra kohta, kus on vaja teha päringuid konkreetselt teie kasutaja alt. Kui te oma kasutaja infot ei lisa, saab teostada vaid avalikke päringuid.

Lisaosa: kohanimede puhverdamine (2p)

Selle lisaosa funktsionaalsus on:

  • asukoha koordinaatide päringu tulemused salvestatakse faili, et järgmisel korral ei peaks neid uuesti küsima (kohalik cache)
  • nimetatud faili saab lisada ise uusi asukohti (näiteks "kodu", "TTÜ" jne)

Puhverdamiseks kasuta faili "kohad.csv", mis peab olema sinu programmile kättesaadav (soovitavalt paikneb samas kataloogis käivitatava klassiga) ja peab koosnema CSV kujul ridadest: 

   ametlik_nimi,latitude,longitude,raadius_km,alternatiivnenimi_1,..,alternatiivnenimi_N

või ridadest, kus koordinaadid ja raadius on puudu: 

   ametlik_nimi,,,,alternatiivnenimi_1,...,alternatiivnenimi_N

kus

  • ametlik_nimi on kohanimi, mida otsitakse API-st
  • alternatiivnimi_1, ..., alternatiivnimi_N on nimed, mida kasutaja saab sisestada. Näiteks saab kasutaja siin määrata "kodu". Kui vastav päring tehakse, otsitakse tegelikult ametlik_nimi asukohta (või kasutatakse juba olemasoelvaid koordinaate ja raadiust, kui need on olemas)
  • latitude, longitude ja raadius_km on standardse tähendusega. Need võivad puududa.

Sinu programm kasutab kohad.csv faili järgmiselt:

  • Enne API poole pöördumist vaatab programm, kas vastav kohanimi on selles failis olemas
    • Kui jah, ja koordinaadid-raadius on antud, kasutab ta koordinaate ja raadiust Twitteri päringu tegemiseks. Asukoha päringut ei tehta
    • Kui jah, aga koordinaadid on puudu, siis
      • teeb uue asukoha API päring ametliku kohanime järgi, leiab koordinaadid ja arvutab raadiuse
      • kirjutab saadud koordinaadid ja raadiuse vastava rea juurde. Järgmisel korral sama päringu puhul pole vaja asukoha API-t enam kasutada.
    • Kui ei, siis tehakse uus päring ning puhverdatakse tulemused faili (kirjutatakse uus rida, kus on ametlik_nimi, koordinaadid ja raadius).

Näited:

1) kohad.csv: 

   tallinn,59.4,24.5,10,kodu,ttü

Kui tehakse otsing "tallinn", siis kasutatakse koordinaate 59.4 ja 24.5, raadius = 10km. Sama juhtub, kui teha päring "ttü", "kodu". kohad.csv fail ei muutu.


2) kohad.csv: 

   pärnu,,,,vanaema,suvila

Kui tehakse otsing "pärnu" või "vanaema" või "suvila", siis otsitakse asukoha API-ga üles "pärnu", loetakse välja koordinaadid ja arvutatakse välja raadius. Tulemuseks on sama rida failis: 

   pärnu,58.3,24.5,5,vanaema,suvila

3) kohad.csv: 

   tallinn,59.4,24.5,10,kodu,ttü

Kui tehakse otsing "pärnu", siis tehakse asukoha otsing "pärnu" ja salvestatakse koordinaadid ja raadius faili. Tulemuseks on fail: 

   tallinn,59.4,24.5,10,kodu,ttü
   pärnu,58.3,24.5,5

See lisaosa täielikult realiseerituna annab 2 punkti.

Pärit leheküljelt "http://courses.cs.taltech.ee/w/index.php?title=ITI0011:Säuts_(2014)&oldid=586"