Oberta API
Codi obert | Contacte

Esdeveniments

Aquest servei permet cercar esdeveniments que tindran lloc en una data o marge de dates.

La url per accedir al servei és:

http://api.oberta.cat/event/search

Per a obtenir la resposta en diferents formats, afegiu l'extensió corresponent:

http://api.oberta.cat/event/search.json, http://api.oberta.cat/event/search.xml

Vegeu l'apartat de formats per a més informació

Paràmetres obligatoris

Api Key (properament)

Si no s'especifica cap més paràmetre, es realitza una cerca dels esdeveniments per a les properes 8 hores. Es pot ajustar aquest número a través del paràmetre h.
Nota Es descarten els esdeveniments que no tenen una hora d'inici definida.

Paràmetres opcionals

Paràmetre Descripció Exemple
h Número d'hores (1-12) per a la qual es vol realitzar la cerca bàsica (esdeveniments que començaran dintre de les properes h hores) Esdeveniments que comencen en la propera hora: http://api.oberta.cat/event/search?h=1
d Data, en format aaaa-mm-dd, per a la qual es realitza la cerca.
Aquest paràmetre s'ignora si es fa servir també el paràmetre h.
Si voleu fer cerques entre dues dates afegiu el paràmetre e. 		Esdeveniments per avui: http://api.oberta.cat/event/search?d=2023-06-07
e Data, en format aaaa-mm-dd, utilitzada conjuntament amb d per a fer cerques entre dues dates. Esdeveniments dins el mes en curs: http://api.oberta.cat/event/search?d=2023-06-01&e=2023-06-30
cat Categoria (id o nom, obtinguts del llistat de categories). Esdeveniments per avui de la categoria "Infantil i juvenil": http://api.oberta.cat/event/search?d=2023-06-07&cat=1
geo Coordenades en format lat,lng respecte les quals es vol realitzar la cerca. Si no especifiqueu un radi (paràmetre rad), s'agafa per defecte un radi de 3km. Esdeveniments per avui al centre de Barcelona: http://api.oberta.cat/event/search?d=2023-06-07&geo=41.386871%2C2.170161
rad Radi en km. (1 - 100) sobre el qual es realitza la cerca geolocalitzada. Esdeveniments per avui en un radi de 20km. del centre de Barcelona: http://api.oberta.cat/event/search?d=2023-06-07&geo=41.386871%2C2.170161&rad=20
q Paraula clau, per a la cerca en el sumari, descripció i localització de l'esdeveniment. Esdeveniments per avui que continguin la paraula "parc": http://api.oberta.cat/event/search?d=2023-06-07&q=parc
pag Número de pàgina (1 - 100). Donat que el nombre màxim d'esdeveniments que es tornen per cada consulta és de 20, podeu fer servir aquest paràmetre per obtenir resultats adicionals en cerques amb més de 20 resultats.
Veieu l'apartat de formats per més informació. 		Esdeveniments per avui, després dels 20 primers: http://api.oberta.cat/event/search?d=2023-06-07&pag=2
after_id Id d'esdeveniment a partir del qual voleu realitzar la cerca. Aquest paràmetre és útil quan guardem esdeveniments en local, i cridem periòdicament el servei web per obtenir possibles esdeveniments introduïts recentment. És a dir, volem repetir una consulta que ja hem fet anteriorment, però sense rebre tots els esdeveniments que ja tenim guardats localment.
Veieu l'apartat de fomats per a més informació. 		Esdeveniments per avui, descartant els esdeveniments amb id més petit o igual a 75: http://api.oberta.cat/event/search?d=2023-06-07&after_id=75
Nota: L'ordre en què es retornen els esdeveniments és per data d'inici, excepte si es fa servir el paràmetre geo, passant llavors a ordenar-se de menor a major distància al punt demanat. En versions posteriors afegirem un paràmetre per a poder especificar l'ordre desitjat.

Formats

Si no poseu cap extensió, el resultat de la cerca es mostrarà en format html. Això està pensat bàsicament per a poder provar de forma senzilla el servei, des d'un navegador.

Per a poder realitzar integracions amb altres aplicacions, podeu fer servir qualsevol dels formats suportats:

Extensió Format Exemple
.json JSON 
{"next":false,"max_id":"76","completed_in":0.195,"events":[{"id":"71","summary":"Visita teatralitzada a la Universitat de Cervera","description":"Direcci\u00f3: Pep Oriol. Amb gui\u00f3 de [...]","location":"Lloc de trobada: Pla\u00e7a Universitat","url":"http:\/\/cultura.gencat.cat\/agenda\/fitxa.asp?fitxa_id=31867","start":"2012-04-08 11:30","end":"2012-12-09","img":"http:\/\/cultura.gencat.cat\/agenda\/media\/universitatcervera.JPG","lat":"41.668320","lng":"1.275151"}]}
.xml XML 
<?xml version="1.0"?>
<response>
<next></next>	
<max_id>76</max_id>
<completed_in>0.195</completed_in>
<events>
 <event id="71">
  <start>2012-04-08 11:30</start>
  <end>2012-12-09</end>
  <summary>Visita teatralitzada a la Universitat de Cervera</summary>
  <description>Direcció: Pep Oriol. Amb guió de [...]
	</description>
  <img>http://cultura.gencat.cat/agenda/media/universitatcervera.JPG</img>
  <url>http://cultura.gencat.cat/agenda/fitxa.asp?fitxa_id=31867</url>
  <location lat="41.668320" lng="1.275151">Lloc de trobada: Plaça Universitat</location>
 </event>
</events>
</response>
.ics iCalendar Pendent d'implementar

Observeu que en els formats xml i json, abans del llistat d'esdeveniments, trobareu els següents valors: