Poet API

A Poet API-ja segítségével elérheted folyamatosan bővülő versadatbázisunkat, és (bizonyos megkötések mellett) ingyenesen és szabadon felhasználhatod azt saját weblapodon, alkalmazásodban vagy más projektedben. A verseket lehetőséged van kategória, szerző vagy szövegrészlet alapján is lekérni. Az API csak azokat a verseket adja vissza, amiknek az utánközléséhez a vers alkotója hozzájárult. Az API használatához programozási tudás szükséges.

A felhasználás feltételei

A Poet API napi 500 lekérésig bárki által használható. Ennél több lekérést igénylő alkalmazások esetében kérünk, hogy előzetesen egyeztess velünk!

A felhasználás feltétele, hogy a verseket, illetve egyéb Poet.hu-ról származó adatokat megjelenítő felület(ek)en forrásmegjelölésként jól látható módon fel legyen tüntetve a Poet.hu. Amennyiben van rá mód, megköszönjük, ha egy ránk mutató linket is elhelyezel alkalmazásod felületén. Az elkészült és publikált alkalmazásod elérhetőségét, kérünk, oszd meg velünk is!

Az API használatához regisztrált felhasználónév szükséges. Egy alkalmazás csak egyetlen felhasználónevet használhat. Tilos az API-t a Poet adatbázisainak reprodukálására, vagy hasonló jellegű adatbázis, illetve weboldal létrehozására használni (a tőlünk kapott adatokat ugyanakkor akár hosszabb távon is eltárolhatod a saját szervereden, ha ez gyorsítja az alkalmazásod működését, és az alkalmazás amúgy megfelel az API-nk felhasználási feltételeinek).

Az Poet írásos engedélye nélkül az API felhasználásával készült alkalmazás nevében nem szerepelhet a "Poet" szó, nem használhatja fel az oldal grafikai elemeit és nem kelthet olyan benyomást, mintha az a Poet hivatalos terméke lenne.

A Poet.hu nem vállal felelősséget a szolgáltatás elérhetőségével vagy működésével kapcsolatban, és fenntartja a jogot, hogy a szolgáltatás nyújtását egyes felhasználók számára akár indoklás nélkül is megtagadja. A beérkezett parancsokat felhasználónévvel és IP címmel együtt 30 napig tároljuk.

Terheléssel kapcsolatos elvárások

Elsődleges célunk a weboldal zavartalan működésének fenntartása. Amennyiben az API használata ezt veszélyeztetni látszik, egyes azonosítókat vagy a szolgáltatást átmenetileg kikapcsolhatjuk. Annak érdekében, hogy erre ne legyen szükség, kérünk, a fejlesztéskor vedd figyelembe az alábbi irányelveinket:

  • A gyakran használt vagy ritkábban változó adatokat átmenetileg tárold a saját szervereden. Ha például a weboldaladon használod az API-nkat, ne intézz kérést a szerverünkhöz minden egyes látogatód érkezésekor - elég, ha egyszer lekéred, amire szükséged van, és elmented a kapott adatokat, hogy a következő látogatóknak külön lekérés nélkül meg tudd mutatni. Letölthető alkalmazás esetén, ha van rá mód, az alkalmazás a te szervereddel kommunikáljon, így az szintén már elmentett adatokat tud az alkalmazásnak továbbküldeni.
  • Az oldalon hajnali 2 és reggel 6 óra között van a legkevesebb látogató, ezért amennyiben az alkalmazásod jellege engedi, ezen időpontok közé időzítsd a lekéréseket. Az esti órákban (18-22-ig) igyekezz minél kevesebb lekérést küldeni felénk!

API dokumentáció

Az API-val való kommunikáció a http protokoll segítségével történik. Az API kéréseket ugyanúgy kell intézni, mintha bármilyen más weboldal tartalmát szeretnéd lekérni. Az API a paramétereket urlencode-olva várja, a választ UTF-8 kódolással fogja elküldeni.

Versek lekérése

URL: http://api.poet.hu/vers.php. Ennek a címnek a segítségével a megadott paramétereknek megfelelő verseket tudsz lekérni.

Kötelező paraméterek:

  • f - A Poet.hu-s felhasználóneved
  • j - A jelszavad alapján képzett egyedi kód. Ha ezt az oldalt bejelentkezés után látogatod meg, a paraméter értékét kiírjuk neked ide.

Választható paraméterek:

Vers forrása:

  • kat - A kategória neve, ahonnan a verseket kéred. A nevet ékezettel, vagy ékezet nélkül is megadhatod.
  • szerzo - A szerző neve, akitől a versek származnak.
  • szoveg - Olyan versek listázása, amikben pontosan megtalálható az itt megadott szó vagy kifejezés.

Egyebek:

  • db - A visszaadott versek száma. Értéke 1 és 5 kötött változhat. Csak akkor használható, ha rendez értéke nem veletlen. Alapértelmezett: 1.
  • rendez - Megadható, hogy a verseket mi szerint rendezze. Értéke lehet: id, ido, szerzo, kedvencek, veletlen. Alapértelmezett: ido. Csak akkor használható, ha a vers forrása meg van adva.
  • rendez_ir - Megadható, hogy a verseket milyen irányban rendezze. Értéke lehet: 0 (növekvő) vagy 1 (csökkenő). Alapértelmezett: 1. Csak akkor használható, ha a vers forrása meg van adva, és rendez értéke nem veletlen.
  • honnan - Megadható, hogy honnan számolja a db darab verset. Ha pl. az első ötöt már lekérted, és a következő öt érdekel, akkor 5-öt adj meg. Csak akkor használható, ha a vers forrása meg van adva, és rendez értéke nem veletlen.

Ha semmilyen választható paramétert nem adsz meg, véletlenszerű verset kapsz.

Példa:

http://api.poet.hu/vers.php?f=[user]&j=[pass]&kat=Szerelem&rendez=veletlen - Egy véletlenszerű verset ad vissza a Szerelem kategóriából.

Válaszpélda:

<?xml version="1.0" encoding="UTF-8"?>
<versek>
  <vers>
	<cim>Én szép világom...</cim>
	<versszoveg>Én szép világom,
Boldogságom.
Arcod borúsnak
Miért látom?
Sóhaj tör elé
Kis szívedből,
Ragyogó könnycsepp
Szép szemedből.

...Ha hű sziveddel
Érzed, érzed,
Hogy el fog veszni
Üdvösséged,
Csókolj meg forrón
Utoljára,
Haljunk meg most a
Boldogságba!...</versszoveg>
	<szerzo>Ady Endre</szerzo>
	<kategoria>Kedvesemnek</kategoria>
	<kategoria>Valentin-nap</kategoria>
	<kedvenc>14</kedvenc>
	<id>15</id>
	<url>http://www.poet.hu/vers/15</url>
  </vers>
  <vers>
	<cim>Húsz év múlva</cim>
	<versszoveg>Mint a Montblanc csúcsán a jég,
Minek nem árt se nap, se szél,
Csöndes szívem, többé nem ég;
Nem bántja újabb szenvedély.

Körültem csillagmiriád
Versenyt kacérkodik, ragyog,
Fejemre szórja sugarát;
Azért még föl nem olvadok.

De néha csöndes éjszakán
Elálmodozva, egyedül
Múlt ifjúság tündér taván
Hattyúi képed fölmerül.

És ekkor még szívem kigyúl,
Mint hosszú téli éjjelen
Montblanc örök hava, ha túl
A fölkelo nap megjelen...</versszoveg>
	<szerzo>Vajda János</szerzo>
	<megjegyzes>Gina emlékkönyvébe</megjegyzes>
	<kategoria>Kihűlt szerelem</kategoria>
	<id>25</id>
	<url>http://www.poet.hu/vers/43</url>
  </vers>
</versek>
Elfogadom

Az oldalon harmadik féltől származó cookie-kat (sütiket) használunk a megjelenő reklámok személyre szabása és statisztikai adatok gyűjtése érdekében. Az oldal használatával elfogadod a cookie-k alkalmazását. Több információ