Lehekülje Sauts lähteteksti vaatamine

<!-- Kõigepealt loe läbi praktikumiülesande spec, siis loe lisaks soovitusi ülesande programmeerimiseks ja näitekoode. -->

= Ülesande spec: mida on tarvis teha =

On vaja kirjutada käsurea rakendus, mis võtab kasutajalt geograafilise asukoha nime 
(näiteks Tallinn, Eesti, Rapla, Harjumaa, Nüpli vms), otsib seejärel twitteri blogisüsteemist 
[http://www.twitter.com twitteri]
api-t kasutades välja viimased kirjed, mis on postitatud enam-vähem sellest piirkonnast ja trükib
need kirjed välja.
    
Näiteks:

     06.09.2008 altexor: Klaxons -a1 disco punk in tallinn. fun   
     06.09.2008 Nath_Milliet: Just booked our plane tickets to go & 
       see Glenn in Tallinn on the 1st of november. I just can't wait :)
     05.09.2008 nolecore: Too much Vana Tallinn....argggghhh    

Ülesanne annab kokku maksimaalselt 10 punkti. Põhiosa annab 5 punkti, täiendavad lisaks. Ilma 
töötava põhiosata lahendust ei aktsepteerita.

Sul võib olla huvitav ennast ise ka Twitter kasutajaks registreerida, kuid ülesande jaoks see kohustuslik ei ole.

== Ülesande põhiosa detailid: kuidas otsing funktsioneerima peab ==

Sinu programm peab kasutama [http://www.twitter.com twitteri] API-t, vt 
[http://apiwiki.twitter.com/Twitter-API-Documentation api seletusi ja juttu].

Selle API abil saad lihtsalt otsida twitteri kasutajate poolt twitteri profiili 
sisestatud asukohta geograafiliste koordinaatide järgi. Twitteri kasutaja ei 
pruugi oma asukohta õigesti sisestada, aga see pole meie mure. Twitteri süstem püüab
kasutaja sisestatud asukoha nime järgi ise tema koordinaate välja rehkendada.

Api näited:

* Kohapõhine otsing atomi formaadis: http://search.twitter.com/search.atom?geocode=59.438862,24.754472,10km
* Kohapõhine otsing jsoni formaadis: http://search.twitter.com/search.json?geocode=59.438862,24.754472,10km

Need URL-d annavad tagasi mingi mõistliku pikkusega listi viimastest sissekannetest 
antud koordinaatidel, antud raadiuse sees. Sina kasuta oma programmi väljundis sedasama listi,
nii palju, kui twitteri API vastuseid annab.

Kui sul ei ole spetsiaalset soovi kasutada jsoni formaati, siis tungiv soovitus on kasutada
siin ülesandes atomi formaati (json sobib väga hästi javascripti rakenduste jaoks).

Nagu näitest näed, peab sinu programm avama urli, mille lõpus on komadega eraldatud:

* laiuskraad (59.438862)
* pikkuskraad (24.754472)
* raadius (10km)

Kuidas saada sisestatud asukoha (Eesti, Tallinn, Rapla jne) koordinaadid? Ülesandes pead siinkohas
kasutama Google mapsi API-t:

* [http://code.google.com/apis/maps/documentation/services.html#Geocoding_Direct Väike API kasutamisjuhend]
* Näide XML formaadis: http://maps.google.com/maps/geo?output=xml&q=tallinn 
* Näide CSV formaadis: http://maps.google.com/maps/geo?output=csv&q=tallinn
* Viimase (CSV) näite oodatav vastus:  200,4,59.438862,24.754472

NB! NB! Kui vajutad ülaltoodud kahele näitelingile, saad tõenäoliselt vale tulemuse, kuhu on sisse
kodeeritud hoopis veateade. Pead näite-urli kopeerima brauseri urli reale ja vajutama enter (või kasutama
hoopis mõnda käsurea-urlilugejat nagu curl), siis töötab ta OK.

Kuna Google CSV-formaat on oluliselt lihtsam, kui XML formaat, siis on siin ülesandes soovitav
kasutada seda.

CSV formaadi vastuse väljad on:

* Asukoha jaoks sobiv zoomi-aste (selle järgi saad pärast valida mõistliku raadiuse!)
* OK/viga kood (200 on ok)
* laiuskraad
* pikkuskraad

NB! laiuskraad ja pikkuskraad tulevad teises järjekorras, kui twitter API neid sööb.

Siin kirjeldatud põhiosa annab niisiis 5 punkti ja tema korrektse töö korral saad praktikumi
arvestatud.

== Ülesande esimene lisaosa: kohad.csv fail ==


See osa on täiendav jupp programmist, mille eesmärgiks on võimaldada 
* ise kohti (kodu, Tehnikaülikool, vanaema_juures jne) kirjeldada
* salvestada Google API antud vastuseid oma faili, et järgmine kord ei peaks uuesti küsima (kohalik cache).

Selleks kasuta faili kohad.csv, mis peab olema sinu programmile kättesaadav (soovitavalt
samas kataloogis) ja peab koosnema CSV kujul ridadest 

    ametlik_nimi,xkoord,ykoord,raadius_km,alternatiivnimi_1,...,alternatiivnimi_N

või ridadest, kus koordinaadid ja raadius puudu:

    ametlik_nimi,,,,alternatiivnimi_1,...,alternatiivnimi_N

kus

* ametliknimi on kohanimi, mida tuleks otsida (kodu asemel näiteks Tallinn, vanaema asemel näiteks Rapla jne)
* alternatiivnimi1,...,alternatiivnimi_N on nimed, mida kasutaja saab sisestada selle koha jaoks
* koordinaadid ja raadius on standardse tähendusega, kuid võivad olla esialgu puudu!

Sinu süsteemi algoritm kohad.csv kasutamiseks:

* Enne Google API kasutamist peab süsteem vaatama kõigepealt, kas antud kohanimi on selles failis. 
* Kui jah, ja koordinaadid antud, siis kasutab neid koordinaate ja Google APIt ei kasuta.
* Kui jah, ja koordinaadid ei ole antud, siis:
** teeb Google API päringu ametliknimi kohta, leiab koordinaadid
** kirjutab need koordinaadid faili vastavale reale juurde: järgmine kord ei ole vaja enam Google API päringut teha.


See moodul annab täielikult realiseerituna 2 punkti.

== Ülesande teine lisaosa: dataen.txt fail ==


See osa on jälle täiendav jupp programmist, mis koha suuruse (ja sobiva raadiuse) hindamisel kasutab
suures failis dataen.txt kodeeritud hinnangut elanikkonna suurusele selles kohas.

Fail on [http://www.world-gazetteer.com/dataen.zip siit downloaditav zip fail] 6.3M, lahti pakkides 23M.

[http://www.world-gazetteer.com/wg.php?x=1129163518&men=stdl&lng=en&gln=xx&dat=32&srt=npan&col=aohdq  Siin on toodud formaadi seletus].

See moodul annab täielikult realiseerituna 2 punkti.

== Ülesande kolmas lisaosa: sorteerimine ==

See osa annab lisaks veel ühe punkti.

Sorteerimisega variandis käivitatakse progamm ühel järgmistest viisidest:

* java findtweets Tallinn
* java findtweets Tallinn name
* java findtweets Tallinn date
* java findtweets Tallinn content

kus esimene variant on varemkirjeldatud ja harilik, teine aga sorteerib ja trükib vastuslisti autori
nime järgi, kolmas sorteerib vastuslisti kirjutamiseaja järgi, neljas sisu järgi.

Kõik neli varianti tuleb realiseerida.

== Ülesande punktid ==

Kokkuvõtlikult:

* Põhiosa: 5 
* kohad.csv fail: 2
* dataen.txt fail: 2
* sorteerimine: 1

= Soovitusi ja ideid programmeerimiseks =

== Võrgust lugemine ==


Kõigepealt soovitan teha eraldi katse selle
http://java.sun.com/docs/books/tutorial/networking/urls/readingURL.html
näiteprogrammiga.

Kui ta ei suuda võrgust lugeda, siis on tõenäoline
põhjus selles, et Sinu arvuti ei saa otse internetti
ühendust, vaid peab töötama läbi nn proxy.

NB! On võimalik (kuid mitte kindel: proovi järgi!)
et kõik AK arvutiklasside arvutid peavad töötama
läbi proxy. Siis viidatud näiteprogramm arvutiklassides
võrgust lugeda otse ei suuda.  Loe [[TTÜ AK proxy]] kohta:
mida TTÜ AK arvutiklassides töötades vaja teha, 
KUI proxy osutub vajalikuks.

Tõenäoliselt aga Sinu koduarvutis või kusagil mujal
arvutis sellist piirangut ei ole ja näiteprogramm
suudab otse võrgust lugeda.

Kui sa ülaltoodud näiteprogrammi järgi url-i avamise ja sealt
lugemise oma programmi sisse paned, siis tuleb nende operatsioonide
ümber tingimata panna try { ... } catch (..) { ... }, täpselt
nagu failioperatsioonidegi ümber.

Lisaks võib sul olla huvitav ja kasulik lugeda [http://java.sun.com/docs/books/tutorial/networking/index.html  Sun-i tutoriali võrgu kasutamiseks]

== Twitteri xml-data kasutamine ==

Kuidas saada twitteri xml-vastusest vajalik info (kuupäev, nimi, sõnum)? Vaata twitteri xml-vastuse source! Otsi sealt oma programmiga järjest stringe:

* <published>...</published> vahel olev string on kuupäev/kell
* <title>...</title> vahel on string on sõnum
* <name>... </name>  vahel enne sulge olev string on autori nimi

Seejärel otsi jälle järgmist jne jne. Soovitan salvestada leitud stringid kahemõõtmelisse stringimassiivi, siis saab neid hiljem sorteerida. Ülesande
põhiosa täitmiseks pole seda massiivi isegi tingimata vaja.

== dataen.txt faili kasutamine ==

Tudeng Sander saatis sellise kogemuse/soovituse, mida tasub järgida:

Raadiuse arvutamisel populatsiooni järgi kasutasin algselt lihtsalt populatsiooni jagamist arvuga. Siis aga oli nii, et kui Tallinnale andis mõistliku raadiuse, siis New Yorgile andis suurema kui terve manner. Ent siis sain aru, et inimeste on linnades võrdeliselt pindalaga (pikkimõõde ruudus), mitte pikkimõõtmega. See tähendab, et raadiusega on võrdeline ruutjuur populatsioonist. Praegu kasutangi raadiuse hinnangu saamiseks 
Math.sqrt(populatsioon) / 40 <- leiutatud arv, esindab ruutjuurt keskmisest inimtihedusest asulates - selle järgi elab asulates keskmiselt 1600 inimest ühel ruutkilomeetril.

Muidugi Lapimaa ja Hiina asulate elanike tihedusel on vahe sees, aga enam-vähem annab mõistlikke numbreid. Tegin veel nii, et miinimum-raadiusest (5km) väiksemat ta ei anna, sest väikestest kohtadest on niikuinii vähe twiterdajaid, pole mõtet võimalusi vähendada.


== Näiteprogrammid ja muud ==

Sul võib olla kasu järgmistest näiteprogammidest:

* [[splitproov.java | splitproov.java]] näiteprogramm sisendteksti tükeldamiseks
* [[massiivproov.java | massiivproov.java]] näiteprogramm massiivide kasutamiseks
* [[ioproov.java | ioproov.java]] näiteprogramm failide kasutamiseks