Citatum API

Mi ez az egész?

A Citatum API-ja segítségével elérheted folyamatosan bővülő és karbantartott idézet- és szerzőadatbázisunkat, és (bizonyos megkötések mellett) szabadon felhasználhatod azt saját weblapodon, alkalmazásodban vagy más projektedben. Az idézeteinket lehetőséged van kategória, szerző, könyv vagy szövegrészlet alapján is lekérni. Az API használatához programozási tudás szükséges.

A felhasználás feltételei

A Citatum API használata non-profit célra napi 500 lekérésig ingyenesen felhasználható. Kereskedelmi, vagy több lekérést igénylő alkalmazások esetében a felhasználhatóság egyedi megállapodáshoz kötött.

A felhasználás feltétele, hogy az idézeteket illetve egyéb Citatum.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 egy oldalunkra mutató link. 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 Citatum adatbázisainak reprodukálására, vagy hasonló jellegű adatbázis, illetve weboldal létrehozására használni.

A Citatum.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.

Idézetek lekérése

URL: http://api.citatum.hu/idezet.php

A fenti cím segítségével a megadott paramétereknek megfelelő idézeteket tudsz lekérni.

Kötelező paraméterek:

f - a Citatum.hu-s felhasználóneved.
j - a jelszavadból generált md5 hash. 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:

Idézet forrása:

kat - A kategória neve, ahonnan az idézeteket kéred.
szerzo - A szerző neve, akitől az idézetek származnak. Megadható teljes név vagy csupán vezetéknév is.
konyv - A könyv címe, amiből az idézetek származnak. A szerző nevének megadása nem kötelező, de a könyv címének pontosan egyeznie kell.
szoveg - Olyan idézetek listázása, amiben pontosan megtalálható az itt megadott szó vagy kifejezés.

Egyebek:

db - A visszaadott idézetek 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 az idézeteket mi szerint rendezze. Értéke lehet: id, ido, szerzo, kedvencek, veletlen. Alapértelmezett: ido. Csak akkor használható, ha az idézet forrása meg van adva.
rendez_ir - Megadható, hogy az idézeteket milyen irányban rendezze. Értéke lehet: 0 (növekvő) vagy 1 (csökkenő). Alapértelmezett: 1. Csak akkor használható, ha az idézet forrása meg van adva, és rendez értéke nem veletlen.
honnan - Megadható, hogy honnan számolja a db darab idézetet. 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 az idézet forrása meg van adva, és rendez értéke nem veletlen.

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

Példák:

http://api.citatum.hu/idezet.php?f=felhasznalonev&j=jelszo&kat=P%E9nz&rendez=veletlen - egy véletlenszerű idézetet ad vissza a Pénz kategóriából.
http://api.citatum.hu/idezet.php?f=felhasznalonev&j=jelszo&szerzo=Albert+Einstein&rendez=kedvencek&db=2 - Albert Einstein két legnépszerűbb idézetét adja vissza.

Válaszpélda:

<?xml version="1.0" encoding="UTF-8"?>
<idezetek>
  <idezet>
	<idezetszoveg>Üres fejjel lehet megélni, üres gyomorral nem.</idezetszoveg>
	<szerzo>Móra Ferenc</szerzo>
	<kategoria>Pénz</kategoria>
	<kategoria>Humor</kategoria>
	<kedvenc>63</kedvenc>
	<id>5073</id>
	<url>http://www.citatum.hu/idezet/5073</url>
  </idezet>
  <idezet>
	<idezetszoveg>Pénz kell-e? izzadj; járj utána, s lesz.</idezetszoveg>
	<szerzo>Vörösmarty Mihály</szerzo>
	<forras>Csongor és Tünde</forras>
	<megjegyzes>1830</megjegyzes>
	<kategoria>Pénz</kategoria>
	<id>6047</id>
	<url>http://www.citatum.hu/idezet/6047</url>
  </idezet>
</idezetek>

Szerző adatok lekérése

URL: http://api.citatum.hu/szerzo.php

A fenti cím segítségével a megadott paramétereknek megfelelő szerzőkről tudsz információkat lekérni.

Kötelező paraméterek:

f - a Citatum.hu-s felhasználóneved.
j - a jelszavadból generált md5 hash. Ha ezt az oldalt bejelentkezés után látogatod meg, a paraméter értékét kiírjuk neked ide.
szerzo - A szerző neve, akinek az adatai érdekelnek. Megadható teljes név vagy csupán vezetéknév is.

Példa:

http://api.citatum.hu/szerzo.php?f=felhasznalonev&j=jelszo&szerzo=Albert+Einstein - Visszaadja Albert Einstein adatait.

Válaszpélda:

<?xml version="1.0" encoding="UTF-8"?>
<szerzok>
	<szerzo>
		<nev>Albert Einstein</nev>
		<szuletett>1879. március 14.</szuletett>
		<meghalt>1955. április 18.</meghalt>
		<szerzoinfo>Nobel-díjas fizikus, a relativitáselmélet megalkotója</szerzoinfo>
		<kep>http://www.citatum.hu/kepek/szerzok/einstein_albert.jpg</kep>
		<kepforras>Oren Jack Turner</kepforras>
	</szerzo>
</szerzok>