Taivaanvahdin hakurajapinta

Taivaanvahdista voi hakea havainto- ja kommenttitietoa HTTP-protokollan GET -tyyppisten kutsujen avulla. Hakurajapinta tulostaa tietoa yleensä neljään eri formaattiin: XML(oletus), HTML, CSV ja JSON. Hakurajapinta noudattaa lukuisia eri parametreja, joita voi käyttää yksin tai yhdistelemällä.
Hakurajapinta on jaettu kahteen osaan: Lisäksi Taivaanvahdin havaintoja on mahdollista liittää suoraan www-sivulle (ohje). Tutustu myös syöttöajapintaan ja yleisiin rajapinnan kättöohjeisiin. Kaikki rajapinnan osta palauttavat tulokset UTF-8 -merkistss.


Taivaanvahdin ksitemalli ja hakurajapintojen osat.


Havaintohaku

versioosoitemuutoskehittäjäjulkaisu
4https://www.taivaanvahti.fi/app/api/search.php?format=htmlPrinttaa CSV:tä, tukee count=1 parametria, columns=all-vipua ja uusia date/year/month/statistical_year -kenttiä Lisäksi mukana on parannettu JSON-formaatti ja tuki monelle havaitsijalle.Emma Bruus02.02.2015
5https://www.taivaanvahti.fi/app/api/search.php?format=htmlSarakkeisiin listty display-parametri ja modstatus -parametri. Emma Bruus17.09.2016
6https://www.taivaanvahti.fi/app/api/search.php?format=htmlSarakkeisiin listty utc ajat, maatiedot ja koordinaattien parametri. Mahdollista hakea maan mukaan ja detail_exact ja title_exact -tapametreilla. Emma Bruus26.03.2017
6https://www.taivaanvahti.fi/app/api/search.php?format=htmlTuotantoversio. Lisätty kenttä likes ja parametrit with_images, with_likes, with_comments Emma Bruus22.08.2019
7https://www.taivaanvahti.fi:8443/app/api/search.php?format=htmlVersio täydellä kielisyystuella. Emma Bruus24.09.2021

Havaintoaika, alku ja loppu

Julkaisuaikarajat

Kategoria

Käyttäjänimi

Paikka

Maa

Vapaa tekstihaku

Näyttävyyshaku

Listätietohaku

Otsikkohaku

  • Parametrin nimi: title, title_exact
  • Muotovaatimus: Hakuparametriin annettava ainakin kolme merkkiä
  • Haku havaintojen otsikoihin. title_exact-versio parametrista tsmää vain tismalleen annettuun merkkijonoon, pelkkä title taas hakee kaikki jossa annettu teksti esiintyy.

Tiimihaku

  • Parametrin nimi: team
  • Muotovaatimus: Hakuparametriin annettava ainakin kolme merkkiä
  • Tiimiperusteinen haku

Displayhaku

  • Parametrin nimi: display
  • Muotovaatimus: Hakuparametrin oltava numeerinen
  • Hakee annettuun nytelmn kuuluvat havainnot. Parametrin arvo on etsityn nytelmn id.

Vain kuvallisten havaintojen haku

Vain kommentoitujen havaintojen haku

Vain tykättyjen havaintojen haku

Lisäsi tuettuja parametreja

  • id: Havainnon yksilöivä numero (vain numeroita)
  • format: Rajapinnan tulostusformaatti, oletusarvoisesti xml (mahdolliset arvot xml/ json/ html/ csv)
  • limit: parametrilla voi asettaa palautettavien hakutulosten maksimimäärän. Ei toimi samalla päivämäärähakujen kanssa.
  • offset: Näytä hakutulokset annetusta järjestysnumerosta alkaen. Ei toimi päivämäärähakujen kanssa.
  • order: Järjestä hakutulokset joko laskevaan tai nousevaan järjestykseen (mahdolliset arvot: asc/desc).
  • orderby: Järjestä hakutulokset annetun kentän mukaan. Mahdolliset arvot: id, user, team, start, city, coordinates, category, showiness, comments ja created. Toimii rajapinnan 3. versiosta eteenpäin.
  • columns: Määrittele mitä kenttiä haluat hakutulokseesi. Erota kenttälista pilkuin. Mahdolliset arvot: id, user, team, start, start_utc, end_utc, city, country, country_name, coordinates, coordinates_estimated, longitude, latitude, category, display, showiness, comments, description, description_formatted, details, more_details, images, likes, thumbnails, equipment, created,year,month,date ja statistical_date. Esim: http://www.taivaanvahti.fi/app/api/search.php?category=halo&columns=user,id,city&orderby=city&start=2013-02-01&format=html&limit=5
    Uusimmassa versiossa toimii myös all, joka antaa kaikki olemassaolevat kentät. Rajapinta saattaa kuitenkin vastata tavallista hitaammin all-kyselyihin.
    http://www.taivaanvahti.fi/app/api/search.php?category=halo&columns=all&orderby=city&start=2013-02-01&format=html&limit=5
  • modstatus -parametrin avulla on mahdollista saada tietoa mys havainnoista, joita ei ole hyvskytty tai jotka odottavat yllpidon ksittelyjonossa. Parametrilla on kaksi mahdollista arvoa 'all' tai 'notapproved'. All listaa kaikki havainnot tilasta riippumatta ja notapproved listaa havainnot, joita ei ole hyvksytty. Huom! Parametrin kytt rajoittaa havainnoista esitettv tietosislt ennalta mriteltyihin kenttiin.
  • coordinates_method -parametrin avulla voit hakea vain sellaiset havainnot joihin havaitsija on itse asettanut koordinaatit (arvo original). Järjestelmän laskemat koodrinaatit voidaan hakea arvolla estimated. Sarakkeen arvot kuvastavat lopputuloksissa tapaa jolla tarkka sijainti on annettu. Arvioiduissa koordinaateissa on keinotekoista hajontaan.
  • language: Tukee kielihaun code -arvoja. Pyrkii parhaansa mukaan esittämään sisällön annetulla kielellä.
Jos tietoja ei lödy, rajapinta ei palauta mitään.

Rajapintahakujen optimointi

Jos olet kehittäsämobiilisovellusta Taivaanvahdin päälle, kannattaa kiinnittää huomiota siirrettävän datan määrään. Tiedonsiirto mobiiliverkossa saattaa olla maksullista ja toisaalta saatavillaoleva kaistakin voi olla tavallista kapeampi.

Siirrettään datamäärään voit vaikuttaa usealla parametrilla. Nästä yksi tärkeimmistä on limit, jolla voit kertoa haluamasi tulosten määrää . Jos sovelluksesi näyttää vain tietyn määrän havaintoja kerrallaan, voit kelata hakutuloksia pala kerrallaan eteenpäin käyttämällä offset parametria. Esimerkiksi limit=100&offset=10 antaa sovelluksellesi ensimmäiset sata hakutulosta, joista tämä haku palauttaa tulokset kymmenestä ensimmäsestä eteenpäin. Voit siis kelata hakutuloksia antamalla ensin offset=0, offset=10, offset=20 jne.

Jos tiedät, että sovelluksesi hakee yleensä tietyn menneen ajanjakson havaintoja (vuosi, edellinen kuukausi), kannattaa aikarajaus liittää mukaan rajapintakyselyyn start ja end -päivä -rajauksin. Koko havaintohistoriaa on turha yrittää hakea yhdellä kertaa, sill&amul; dataa on liian paljon. Jos jostain syystä haluat noutaa suuria aineistoja, poimi ne vuosi kerrallaan.

Mikäli sovelluksesi hakee rajapinnan kautta tietoja usein, kannattaa tutustua myös columns parametrin käyttöön. Sovelluksesi ei todennäkösesti tarvitse kerralla aivan kaikkea tarjollaolevaa havaintoon liittyvää dataa, joten voit parametrin avulla hakea vain tarvitsemasi kentä. Columns-parametrille annetaan pilkulla erotettuna näytettävien kenttien lista. Listan arvot ovat tällä sivulla mainittuja parametrien nimiä Esim. columns=nimi,title,city,comments. Parametrin käytöllä on suora vaikutus siirrettyn datan määrään, mutta sen huolellisella käytöllä pystyt parantamaan myös palvelimen suorituskykyä. Palvelin saattaa hyvin suurissa kuormitustilanteissa (jonkin näyttävän tainvaanilmiön aikana) vastata tavallista hitaammin. Voit itse auttaa palvelinta pärjäämään vaikeassa tilanteessa kyselemälä rajapinnasta vain rajallista datasettiä.

Tällä hetkellä kaikki rajapinnan versiot hyödyntävät memcache-väimuistiteknologiaa palvelimen kuorman helpottamiseksi. Hakutulokset tallennetaan aina minuutiksi ja uudelleenkäytetään jos sama kysely saapuu minuutin sisälä uudestaan.

Varautuminen rajapinnan muutoksiin

Toteutettaessa sovelluksia rajapinnan plle, toteuttajan tulee huomioida, ett rajapinnan osiin saatetaan tulevaisuudessa tuoda uutta tietosislt. Kytnnss tm tarkoittaa sit, ett sovelluksen toteutus on tehtv niin, ett uusi arvo rajapinnassa ei riko sen toiminaa. Rajapintaan on tyypillisesti voitu list uusia columneja ja parametreja.


Kommenttihaku

Osoite: http://www.taivaanvahti.fi/app/api/comment_search.php

Kommentointiaika, alku ja loppu

Havainnon kommentit

Kommentoineen havaisijan nimi

Vapaa tekstihaku kommenteista

Lisäsi kommenttihaussa tuettuja parametreja

  • id: Kommentin yksilöivä numero (vain numeroita)
  • format: Rajapinnan tulostusformaatti, oletusarvoisesti xml (mahdolliset arvot xml/ json/ html/ csv)
  • limit: parametrilla voi asettaa palautettavien hakutulosten maksimimäärän. Ei toimi samalla pävääräakujen kanssa.
  • offset: Näytä hakutulokset annetusta järjestysnumerosta alkaen. Ei toimi päivämäärähakujen kanssa.
  • order: Järjestä hakutulokset joko laskevaan tai nousevaan järjestykseen (mahdolliset arvot: asc/desc).

Etusivun uutisten haku

Osoite:
https://www.taivaanvahti.fi/app/api/news.php
  • format: Rajapinnan tulostusformaatti, oletusarvoisesti xml (mahdolliset arvot xml/ json/ html / csv)
  • limit: parametrilla voi asettaa palautettavien hakutulosten maksimimäärän.
  • text: tekstihaku uutisiin
  • language: Tukee kielihaun code -arvoja. Pyrkii esittämään sisällön annetulla kielellä.

Havaintokategorioiden haku

Lhinn mobiiliclienttej varten.

Osoite:
https://www.taivaanvahti.fi/app/api/categories.php

Parametrit:

  • format: Tukee eri formaatteja (xml, json, html, csv).
  • language: Tukee kielihaun code -arvoja. Pyrkii esittämään sisällön annetulla kielellä.


Kielivaihtoehtojen haku

Lhinn mobiiliclienttej varten. Tulee vain GET-muotoisia kutsuja.

Osoite:
https://www.taivaanvahti.fi/api/getLanguagesRequest/json/

Parametrit:

  • format: Tukee formaatteja xml (oletusarvo) ja json.


Taivaanvahdin rajapinnan käyttö Google-sheeteillä

Taivaanvahdin dataa pystyy noutamaan Googlen taulukkolaskentaan ja jatkojalostaa dataa siellä.

  • 1. Muodosta datan noutoon tarvittavan rajapintalyselyn GET-osoite/url
  • 2. Liitä rajapinta-url IMPORTXML -lausekkeen sisään siillä taulukon lehdellä, jossa haluat selata dataa
Tämä diipadaapa siis pudotetaan taulukon soluun muuntaen kutsua sisältämään halutut kentät:

=IMPORTXML("https://www.taivaanvahti.fi/app/api/search.php?format=xml&cat=2&text=komeetta&start=2022-01-01&orderby=start_utc&order=asc&columns=id,start,start,start_utc,end,end_utc,city,coordinates,country,user,link&";"results/observation";"fi")
Vinkki: kannattaa noutaa aineisto kerralla yhdelle lomakkeen lehdelle ja poimia siitä eteenpäin muille taulukkokokonaisuuden lehdille esim. yhteenvetoa tai summia varten.

Emma Bruus 2022-05