API de Dades Obertes del CIDO
Una API o interfície de programació d’aplicacions és un conjunt de mètodes que recuperen dades perquè puguin ser processades per altres aplicacions.
Un cop es coneix l’estructura de les dades, només cal cridar els mètodes corresponents, tenint en compte que es poden combinar els mètodes entre si.
Taula de continguts
- 5039 lectures
| Adjunt | Mida |
|---|---|
 documentacio_api_cido.pdf | 4.4 MB |
Què és una API REST?
Una API o interfície de programació d’aplicacions és un conjunt de mètodes per recuperar dades perquè puguin ser processades per altres aplicacions.
REST és una arquitectura de software per a sistemes hipermèdia. Actualment REST és el terme que s'utilitza per descriure tota interfície entre sistemes que utilitzi el protocol HTTP per a determinar operacions a ser executades sobre un conjunt de dades o directament obtenir-les, formatades i sense les complicacions pròpies de realitzar aquesta tasca a un nivell més directe.
Un cop es coneix l’estructura de les dades, només cal cridar els mètodes corresponents, tenint en compte que es poden combinar els mètodes entre si.
- 225 lectures
Estàndard
El Cercador d’Informació i Documentació Oficials (CIDO) ofereix una API de dades obertes per poder realitzar consultes M2M (machine to machine). L’API està basada en l’estàndard JSON:API v1.0 (https://jsonapi.org/).
- 170 lectures
Estructura de la base de dades
La base de dades del CIDO estructura la informació de forma relacional, les dades s’emmagatzemen en registres organitzats en taules que es relacionen entre sí. Donat que aquesta estructura relacional s’ha mantingut en l’API de dades obertes, cal tenir en compte el següent:
- Les dades comunes a la norma o procediment estan emmagatzemades en una taula. Aquesta taula es correspon amb l’entitat de l’API anomenada com a tal. Per exemple, l’entitat Oposicions conté les dades fixes, les que no varien dins un procés de selecció (expedient, tipus de personal, grup de titulació, accés al tràmit, etc.).
- S’emmagatzemen en taules diferents aquelles dades d’un tipus d’informació pública que impliquen una relació d’un a molts registres (documents, matèries, beneficiaris i dades econòmiques). Per mostrar aquestes dades a l’API, s’estableixen una sèrie de relacions, com ara oposicions-documents. Aquest dataset conté les dades dels anuncis o fases d’un procés de selecció i es relacionen entre sí a través del camp id de l’oposició.
- Les relacions entre les diferents entitats de l’API són bidireccionals. Per exemple, la relació entre les entitats oposicions i materies permet extreure dos datasets: oposicions-materies, que mostra les matèries d’una oposició concreta; i materies-oposicions, que mostra les oposicions d’una matèria concreta.
- No totes les taules de la base de dades del CIDO tenen una entitat pròpia a l’API, les seves dades es recuperen directament en els principals datasets.
- Els filtres Institució, Matèria i Qui ho pot sol·licitar del web del CIDO tenen una estructura de nodes, de tal manera que, en aplicar un filtre, es retornen els resultats no només del registre seleccionat, sinó també dels registres jeràrquicament inferiors. Per exemple, si es filtra per la institució Diputació de Barcelona, retorna no només els registres que tenen assignada aquesta institució, sinó també tots aquells que tenen qualsevol altra institució depenent (gerències, serveis, etc.).
- El filtre Municipi disponible al web del CIDO als apartats de Subvencions i Normativa local permet recuperar els ajuts o la normativa que poden ser d’interès per a les persones usuàries tenint en compte el seu àmbit territorial. Per exemple, a l’apartat de Subvencions, partint del nivell territorial més baix (municipi), s’obtenen les subvencions a les quals pot optar qualsevol col·lectiu (persones, entitats sense ànim de lucre, empreses, etc.) que resideix o té seu en un determinat municipi.
- 231 lectures
Estructura de les dades
Per estructurar les dades de l’API s’utilitzen els següents conceptes:
- Entitat: tipus de contingut concret a partir d'un nombre arbitrari de camps i relacions. Per exemple, l’entitat oposicions conté tots els camps relatius a un procés de selecció (títol, identificador, titulació requerida, data de finalització, etc.) i les seves relacions (matèries, institució i documents).
- Dataset: conjunt de dades d'un tipus d’entitat concreta. Per exemple, el dataset oposicions-matèries conté les dades de les matèries d’una oposició.
- Relació: les relacions ens permeten connectar dades d’una entitat amb un dataset concret o amb una altra entitat. Per exemple, es poden relacionar les entitats beneficiaris i subvencions a partir d’un identificador únic (codi id del beneficiari).
- Camp: els camps defineixen els diferents valors que pot tenir un tipus de contingut. Els camps tenen diferents propietats:
- Nom: etiqueta per identificar el camp en l'interacció amb l’API.
- Descripció: descripció del contingut del camp.
- Tipus: indica com està definit el valor del camp. Pot ser long, string, boolean, date o decimal.
- Pes: valor que s'utilitza per ordenar els camps dins d'un registre.
- Obligatori: indica que en tot registre aquest camp ha de tenir un valor assignat.
- Únic: indica que el valor del camp no es pot repetir en la resta de registres d'un mateix dataset.
- Multivaluat: indica que el camp pot prendre més d'un valor.
- Primari: indica que aquest camp identifica el registre del que forma part, per tant, també té un valor únic dins el mateix dataset.
- 151 lectures
Tipus de camps i propietats
L'API de dades obertes consta de diferents tipus de camps i cada camp pot tenir diferents propietats:
Tipus de camps
- String: camp de text.
- Long: camp numèric.
- Boolean: camp de tipus lògic que representa els valors true o false.
- Date: camp de data amb el format aaaa-mm-dd.
- Decimal: camp numèric que admet decimals. S’utilitza el punt pels decimals.
Propietats dels camps
- Clau primària: camp identificador del recurs. Sempre està informat i és únic.
- Multivaluat: el camp permet més d'un valor.
- Obligatori: el camp és obligatori.
- Únic: el valor del camp és únic i no es repeteix en cap altre registre.
- 173 lectures
Mètodes i crida de l'API
Per obtenir una llista de resultats d’una entitat es farà servir la següent estructura:
/cido/v1/nomEntitat
Per obtenir les dades d’un registre concret es farà servir la següent estructura:
/cido/v1/nomEntitat/id
Cada entitat pot tenir diverses relacions (veure apartat de relacions).
Per obtenir les dades de la relació es farà servir la següent estructura:
/cido/v1/nomEntitat/id/nomRelacio
- 234 lectures
Filtres
Per aplicar filtres a les cerques s’ha de fer servir el paràmetre filter amb el següent format:
- filter[nomDelCamp][operador]=valor
- filter[nomDelCamp]=valor
- filter[nomRelacio.nomDelCamp][operador]=valor
- filter[nomRelacio.nomDelCamp]=valor
Si no s’informa l’etiqueta [operador] es considerarà [EQ] per defecte. I la concatenació de múltiples paràmetres filter aplicarà un AND entre ells.
- 157 lectures
Filtres avançats
Es poden aplicar filtres avançats fent servir JSON com a valor del paràmetre filter. Per exemple, per aplicar un OR entre múltiples paràmetres, els valors hauran d’estar separats per comes (,):
- filter[idEstat]=1,2,3
- filter={“OR”:[{“idEstat”:1},{“idEstat”:2},{“idEstat”:3}]}
Aquest filtre retornaria les entitats que compleixin: idEstat = 1 OR idEstat = 2 OR idEstat = 3.
Si el filtre es realitza sobre una relació:
- filter[materies.id]=204,781,773
- filter={“materies”:{“OR”:[{“id”:204},{“id”:781},{“id”:773}]}}
- 138 lectures
Filtre per nodes
La funcionalitat de filtrar per nodes es troba disponible a les entitats institucions, materies i beneficiaris.
Per recuperar els anuncis d’una institució concreta i de les institucions jeràrquicament inferiors a aquesta (node), s’estableixen relacions amb el següent format:
/cido/v1/institucions/id/nomEntitat-relacionades
Per exemple, per obtenir les oposicions d’una institució concreta i de les institucions jeràrquicament inferiors a aquesta:
/cido/v1/institucions/id/oposicions-relacionades
Aquesta mateixa relació també permet recuperar les dades a la inversa, és a dir, les institucions jeràrquicament superiors a la institució d’un anunci. Per exemple, per obtenir la institució d’una oposició i les institucions jeràrquicament superiors a aquesta:
/cido/v1/oposicions/id/institucions-vinculades
- 74 lectures
Filtre per territori d'aplicació
La funcionalitat de filtrar per territori d’aplicació es troba disponible a les entitats subvencions i normatives-locals.
Per recuperar els anuncis que apliquen en un municipi concret es disposa de les següents relacions:
- Subvencions: /cido/v1/institucions/id/subvencions-impacte
- Normativa local: /cido/v1/institucions/id/normatives-locals-impacte
També es poden obtenir les dades dels municipis en els quals impacta una subvenció o normativa amb la següent estructura:
/cido/v1/nomEntitat/id/municipis-impacte
Aquesta funcionalitat només és aplicable als 947 ajuntaments de Catalunya.
- 74 lectures
Operadors
Els operadors admesos són els següents:
- EQ: igual.
- NEQ: no igual.
- LIKE: conté. Aquest operador es pot fer servir amb %25 (caràcter: %) com a comodí.
- LT: més petit que.
- LE: més petit o igual que.
- GT: més gran que.
- GE: més gran o igual que.
Hi ha alguns caràcters especials que han d’anar codificats de manera que siguin vàlids a la URL. Alguns exemples:
- %: %25
- &: %26
- =: %3D
- 87 lectures
Paginació
Per aplicar la paginació cal fer servir els següents paràmetres:
- Per aplicar un màxim de resultats: page[limit]=maxResultats
Per defecte es retornen 500 resultats i com a màxim es poden demanar 2.000 resultats en cada consulta.
- Per obtenir resultats d’una altra pàgina, cal indicar que volem “saltar” X número de resultats previs: page[offset]=resultatsSaltar
Generalment, el número de resultats a saltar (offset) correspon al número de pàgina que es vol obtenir (començant per la pàgina 0) multiplicat pel número de resultats (límit) que s’obtenen per pàgina.
- 79 lectures
Ordenació
Per ordenar els resultats de cerques cal fer servir el paràmetre sort indicant com a valor els camps que es faran servir per l’ordenació. Si un camp està precedit per -, voldrà dir que s’ordenarà de manera descendent.
Per exemple:
- sort=titol
- sort=-titol
- 55 lectures
Retorn de resultats
L’API retornarà resultats de dos tipus:
- Resultats de tipus llistat: retornarà 0, 1 o múltiples resultats. En aquest cas, el camp data del JSON consistirà en un array de resultats.
- Cap resultat: []
- Un resultat: [{entitat1}]
- Múltiples resultats: [{entitat1}, {entitat2}, ...]
- Resultats de tipus entitat: retornarà 0 o 1 resultat. En aquest cas, el camp data del JSON consistirà en un objecte.
- Cap resultat: null
- Un resultat: {entitat1}
- 105 lectures
Exemples de crides
Oposicions
Borses de treball d'accés lliure de les administracions públiques catalanes:
Oposicions d'accés lliure de les administracions publiques catalanes:
https://api.diba.cat/dadesobertes/cido/v1/oposicions?sort=-maxDataPublicacioDocument
Oposicions d'accés lliure de les administracions públiques catalanes amb el termini de presentació d'instàncies obert:
Oposicions d'accés lliure de les administracions públiques catalanes convocades pel sistema de concurs:
Oposicions d'accés lliure de les administracions públiques catalanes convocades en règim d'interinatge:
Oposicions d'accés lliure de la Diputació de Barcelona:
Oposicions d'accés lliure de les administracions públiques catalanes amb places reservades a persones amb discapacitat:
Oposicions d'accés lliure de les administracions públiques catalanes amb places reservades a joves:
Oposicions d'accés lliure de les administracions públiques catalanes amb places reservades a aturats:
Oposicions d'accés lliure de les administracions públiques catalanes amb places reservades a dones:
Contractació
Licitacions obertes de contractes administratius o privats que afecten l'àmbit territorial català:
Contractes de gestió i prestació de serveis que afecten l'àmbit territorial català:
Contractes d'obres que afecten l'àmbit territorial català:
Contractes privats que afecten l'àmbit territorial català:
Contractes de subministraments que afecten l'àmbit territorial català:
Contractes administratius o privats que afecten l'àmbit territorial català:
https://api.diba.cat/dadesobertes/cido/v1/contractacions?sort=-maxDataPublicacioDocument
Oportunitats de negoci amb el sector públic d’agroalimentària:
Oportunitats de negoci amb el sector públic d’assessorament, estudis i anàlisis:
Oportunitats de negoci amb el sector públic de construcció i instal·lacions:
Oportunitats de negoci amb el sector públic d’educació, cultura i oci:
Oportunitats de negoci amb el sector públic d’energia:
Oportunitats de negoci amb el sector públic d’activitats financeres i d’assegurances:
Oportunitats de negoci amb el sector públic de salut, serveis socials, protecció i neteja:
Oportunitats de negoci amb el sector públic de sanejament i residus:
Oportunitats de negoci amb el sector públic de TIC:
Oportunitats de negoci amb el sector públic de transport i logística:
Oportunitats de negoci amb el sector públic de turisme i hostaleria:
Subvencions
Beques adreçades a qualsevol col·lectiu de Catalunya:
Cursos adreçats a qualsevol col·lectiu de Catalunya:
Premis adreçats a qualsevol col·lectiu de Catalunya:
Subvencions adreçades a qualsevol col·lectiu de Catalunya:
Subvencions adreçades als ens locals de Catalunya
Ajuts adreçats a la ciutadania de Catalunya:
Ajuts adreçats a estudiants:
Ajuts adreçats a infants i famílies:
Ajuts adreçats a personal de l’Administració pública:
Ajuts adreçats a personal docent:
Ajuts adreçats a persones amb discapacitat:
Ajuts adreçats a dones:
Ajuts adreçats a gent gran:
Ajuts adreçats a joves:
Ajuts adreçats a personal d’investigació i recerca:
Ajuts adreçats a persones a l’atur:
Ajuts adreçats a titulats universitaris:
Ajuts adreçats a persones en situació de vulnerabilitat:
Ajuts adreçats al teixit productiu:
Ajuts adreçats a les empreses:
Ajuts adreçats a la petita i mitjana empresa:
Ajuts adreçats a professionals i autònoms:
Ajuts per a fer front a la crisi ocasionada per la COVID-19 adreçats a qualsevol col·lectiu:
Ajuts per a fer front a la crisi ocasionada per la COVID-19 adreçats a persones i famílies:
Ajuts per a fer front a la crisi ocasionada per la COVID-19 adreçats al teixit productiu:
Subvencions que apliquen al municipi d’Abrera:
Normativa local
Calendaris i padrons fiscals de l'Administració local catalana:
Estatuts d'ens que pertanyen a l'àmbit territorial català:
Ordenances i convenis tipus de les administracions públiques catalanes:
Ordenances fiscals:
Ordenances reguladores i reglaments de l'Administració local catalana:
Pressupostos i plantilles de l'Administració local catalana:
Normativa local que aplica al municipi de Gavà:
Normativa local d’afectació a Gavà en matèria de serveis socials:
Normativa local que regula l’activitat empresarial a Gavà:
Mesures adoptades pels ens locals per fer front a la crisi ocasionada per la COVID-19:
Convenis col·lectius
Convenis col·lectius d'empreses publicats al BOE, al DOGC i als butlletins provincials de Catalunya:
Pactes i acords del personal al servei dels ajuntaments de Catalunya publicats al BOE, al DOGC i als butlletins provincials de Catalunya:
Convenis col·lectius que afecten un sector determinat, d'àmbit territorial català o estatal, publicats al BOE, al DOGC i als butlletins provincials de Catalunya:
Convenis col·lectius d'ens no municipals, ni empresarials publicats al BOE, al DOGC i als butlletins provincials de Catalunya:
Institucions
Institucions de la comarca del Baix Llobregat:
Consorcis d’àmbit local:
Matèries
Matèries de l’apartat Oposicions:
https://api.diba.cat/dadesobertes/cido/v1/materies?filter[idModul]=4&sort=materia
Beneficiaris
Beneficiaris dependents de Teixit productiu:
- 578 lectures