Citatum API

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) ingyenesen és 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 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 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 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 Citatum írásos engedélye nélkül az API felhasználásával készült alkalmazás nevében nem szerepelhet a "Citatum" szó, nem használhatja fel az oldal grafikai elemeit és nem kelthet olyan benyomást, mintha az a Citatum hivatalos terméke lenne.

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. Ennek a címnek a 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. A nevet ékezettel, vagy ékezet nélkül is megadhatod.
  • 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, amikben 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.
  • minhossz - A visszaadott idézetek minimális hossza. Minimum 1.
  • maxhossz - A visszaadott idézetek maximális hossza. Minimum 1.
  • felkerult - Az idézet felkerülése óta eltelt napok száma. Minimum 1.
  • 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=Penz&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. Ennek a címnek a segítségével a megadott paramétereknek megfelelő szerzőkről tudsz információkat lekérni. Kérlek, vedd figyelembe, hogy ha a szerző portréját megjeleníted, akkor - amennyiben ez meg van adva - valamilyen módon a kép forrását is meg kell jelenítened (pl. a képre állva buborékban)!

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>