Näytelmähaku

Näytelmätietoa voi hakea HTTP-protokollan GET -tyyppisten kutsujen avulla. Muun hakurajapinnan tavoin näytelmähaku tulostaa tietoa kolmeen eri formaattiin: XML (oletus), HTML, CSV ja JSON. Näytelmähaku noudattaa lukuisia eri parametreja, joita voi käyttää yksin tai yhdistelemällä. Kuten muutkin Taivaanvahdin rajapinnat, myös näytelmähaku palauttavat tulokset UTF-8 -merkistössä.

versioosoitemuutoskehittäjäjulkaisu
1https://www.taivaanvahti.fi/app/api/display_search.phpAlkuperänen versioEmma Bruus8.11.2016

Alku ja loppu

Vuosi

Päivä

Päivämääräväli

Aika suhteessa nykyhetkeen

  • Parametrin nimi: time
  • Mahdolliset arvot:
    • now - uudet näytelmät / nyt päällä
    • today - näytelmät 24h sisällä
    • 1d tai yesterday - näytelmät eilen ja tänään
    • 2d,3d,4d,5d - näytelmät 2,3,4,5 päivää sitten
    • week - viikon sisällä
    • month - kuukauden sisällä
    • year - vuoden sisällä
  • Listaa kaikki yhtenä päivänä näkyvissä olleet näytelmät.
  • Esim: https://www.taivaanvahti.fi/app/api/display_search.php?format=html&time=week

Havainto

Kategoria

Näytelmätyyppihaku

Otsikkohaku

Havaintojen määrä

Harvinaiset näytelmät

Lisäsi tuettuja parametreja

  • id: Näytelmän 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:
    • start - järjestää näytelmän alkuajan mukaan,
    • observation_count - havaintomäärän mukaan ,
    • major - harvinaislaatuisten näytelmien mukaan
  • columns: Määrittele mitä kenttiä haluat hakutulokseesi. Erota kenttälista pilkuin. Mahdolliset arvot:
    • tiny - tulostaa pelkän otsikkotason,
    • no_details - näytelmän pääpiirteet, ei yksityiskohtia,
    • no_observations - ei havaintoja
  • count: Listaa vain tulosten lukumäärän kaikki motoiluparametrit ohittaen.

Näytelmät havaintohaun puolella

Myös yksittäisten havaintojen haku tukee parametria display. Antamalla näytelmän numeron ehdoksi havaintojen hakurajapinnalle saat suodattamattomana kaikki näytelmän havaintojen tietot. Esim: http://www.taivaanvahti.fi/app/api/search.php?format=html&display=56113

Havaintohaun antamat tiedot sisältävät lisäksi havainnon näytelmän numeron, jos havainto kuuluu johonkin näytelmään.

Optimoinnista

Jos teet www-pohjaista sovellusta hakurajapinnan päälle, on suositeltavaa että optimoit ratkaisua, niin ettei havaintopalvelu kuormitu turhaan. Käytännössä tämä voi tarkoittaa esim. välimuistin (memcache, elastic search, tekstitiedosto...) käyttöä jonkun tietyn tulosjoukon tilapäisenä välivarastona. Taivaanvahti saattaa kirkkaiden taivaanilmiöiden aikaan kuormittua huomattavasti ja vastata hitaasti rajapintakyselyihin.

Mikäli kehität sovellusta mobiililaitteille, pystyt rajoittamaan lähetettävää tietosisältöä pienemmäksi esim. käyttämällä columns=no_observations -parametriasetusta. Pystyt myös palastelemaan clientille lähetettäviä tietopyyntöjä pienemmäksi käyttämällä limit ja offset -parametreja.

Jos haluat vain sellaiset näytelmät, joihin kuuluu useampi havainto, kannattaa ottaa käyttöön observation_count -rajoitus. Asetuksella observation_count=2 voit karsia yhden havainnon näytelmät pois tietovirrasta.

Emma Bruus 2016-11