Cerca de població. API

1.1. Anatomia de les peticions

Tota petició ha d'especificar obligatòriament el servei, la versió, l'operació i el format. Versió i operació són característiques específiques de cada servei. A més dels formats de resposta generals de les APIs de l'Idescat, per conveniència el servei de Cerca de població suporta el format text en l'operació sug. Per a més informació, consulteu l'apartat Anatomia de les peticions a la documentació general de les APIs de l'Idescat.

1.1.1. Identificador del servei i versió

L'identificador d'aquest servei és pob.

https://api.idescat.cat/pob/v1/{…}

1.1.2. Operacions

Admet dos tipus d'operacions:

• cerca: Retorna resultats d'una cerca per nom d'entitat territorial amb informació sobre la seva població. Vegeu l'apartat 1.2..

  https://api.idescat.cat/pob/v1/cerca.{…}

• sug: Retorna la llista d'entitats territorials que comencen pels caràcters especificats. Vegeu l'apartat 1.2..

  https://api.idescat.cat/pob/v1/sug.{…}

1.2. Paràmetres específics

Els paràmetres específics ("variables") permeten escollir la informació que retornarà una determinada operació del servei. Es poden especificar com a paràmetres individuals o en un únic paràmetre p (forma compacta). En aquesta documentació, s'utilitza sempre la forma compacta.

Per conèixer els paràmetres generals disponibles per a qualsevol servei, consulteu la documentació de les APIs de l'Idescat.

1.2.1. Paràmetres específics comuns a totes les operacions

1.2.1.1. Filtre q

Tant l'operació cerca com l'operació sug permeten seleccionar les entitats territorials que s'inclouran a la resposta segons la seva denominació utilitzant el paràmetre q. El significat d'aquest paràmetre varia segons l'operació.

• Operació cerca: Selecciona entitats territorials que continguin la cadena de caràcters especificada. És un paràmetre opcional.
• Operació sug: Selecciona entitats territorials que comencin amb la cadena de caràcters especificada. És un paràmetre opcional, però si no s'especifica o el seu valor té menys de dos caràcters, no es retornarà cap resultat.

Ex. 1: Llista d'entitats territorials que comencen amb "ab", separades per salts de línia

https://api.idescat.cat/pob/v1/sug.txt?p=q/ab

1.2.1.2. Filtre tipus

Tant l'operació cerca com l'operació sug permeten seleccionar les entitats territorials que s'inclouran a la resposta d'acord amb la tipologia següent:

• cat: Catalunya
• prov: Províncies
• atp: Àmbit territorial de planificació del Pla territorial general de Catalunya
• com: Comarques
• mun: Municipis
• ec: Entitats col·lectives
• es: Entitats singulars
• np: Nuclis de població
• dis: Disseminats (aquest valor pot no donar cap resultat perquè, almenys en el moment de redactar aquesta documentació, no hi havia a Catalunya cap entitat disseminada que tingués un nom específic)

Aquests valors es poden concatenar separats per comes. Per defecte, tipus és igual a cat,prov,atp,com,mun,ec,es,np,dis.

Ex. 2: Llista de municipis i nuclis de població que comencen amb "ab", en format text

https://api.idescat.cat/pob/v1/sug.txt?p=q/ab;tipus/mun,np

Ex. 3: Població de totes les comarques de Catalunya, en format XML

https://api.idescat.cat/pob/v1/cerca.xml?p=tipus/com

1.2.2. Paràmetres específics de l'operació cerca

1.2.2.1. Filtre sim

Els resultats de l'operació cerca tenen associada una categoria de similitud amb la cadena q buscada. El paràmetre sim permet filtrar els resultats segons aquesta similitud:

• 0: Només es retornen les entitats territorials la denominació de les quals coincideix amb l'especificada a q (ignorant majúscules i minúscules i accents). Cal tenir en compte que la denominació utilitzada aplica la normativa oficial de la llengua catalana segons la qual els articles que acompanyen topònims en una llista s'escriuen a la dreta del topònim en minúscula i després d'una coma, per tal de respectar l'ordenació alfabètica. Aquesta norma és vàlida per a qualsevol tipus d'article normatiu, sigui normal, amb apòstrof o salat (per exemple, «Agaró, s'»).
• 1: Només es retornen les entitats territorials que contenen la cadena q especificada com a paraula (o expressió) i no estan incloses a l'apartat anterior.
• 2: Només es retornen les entitats territorials que contenen la cadena q especificada com a fragment i no estan incloses als apartats anteriors.

Aquests valors es poden concatenar separats per comes. Per defecte, sim és igual a 0,1,2.

Ex. 4: Població de les entitats territorials que es diuen "abrera" o contenen aquest nom, en format JSON

https://api.idescat.cat/pob/v1/cerca.json?p=q/abrera;sim/0,1

1.2.2.2. Filtre selec

En la majoria de casos, l'API és capaç de suggerir un resultat destacat fins i tot quan hi ha més d'una entitat territorial en la categoria de similitud 0 (vegeu l'apartat 1.2.2.1. Filtre sim). Per fer-ho, té en compte la tipologia d'entitats territorials (vegeu l'apartat 1.2.1.2. Filtre tipus), prioritzant-les en aquest ordre:

• Municipis
• Províncies
• Entitats col·lectives
• Entitats singulars
• Nuclis de població
• Disseminats

El paràmetre selec permet simplificar la resposta perquè contingui només un resultat (o cap).

• 1: La resposta només inclou el resultat destacat (si n'hi ha).
• 0: La resposta inclou tots els resultats. És el valor per defecte.

Ex. 5: Resultat destacat per a la cerca "abrera", en anglès i en format JSON amb funció de devolució ("f")

https://api.idescat.cat/pob/v1/cerca.json?p=q/abrera;selec/1&callback=f&lang=en

1.2.2.3. Paràmetre orderby

Els resultats es mostren ordenats per proximitat amb la cerca efectuada: nom de l'entitat igual al text cercat, nom amb la paraula o expressió sencera cercada i nom que conté el text cercat com a fragment no sencer. El paràmetre orderby permet determinar l'ordenació dels resultats dins d'aquesta ordenació general. Admet els valors següents:

• tipus: L'ordenació dels resultats prioritza el tipus d'entitat. És el valor per defecte.
• nom: Els resultats s'ordenen alfabèticament segons el nom de l'entitat territorial.

1.2.2.4. Paràmetre posicio

Com algunes cerques poden retornar un nombre molt elevat de resultats, la resposta no sempre els inclourà tots. El paràmetre posicio permet determinar quin és el primer resultat inclòs a la resposta. Per defecte, posicio és igual a zero (es retornen resultats començant pel primer).

1.3. Invocació sense operació

Per raons d'amigabilitat, aquesta API admet peticions amb una sintaxi que no requereix especificar operacions (vegeu, a la documentació general de les APIs de l'Idescat, l'apartat 1.4. Invocació sense operació).

• Llista d'entitats territorials que comencen amb "ab" en format text

  https://api.idescat.cat/pob/v1/geo.txt?sug=ab

• Població de totes les comarques de Catalunya en format XML

  https://api.idescat.cat/pob/v1/geo.xml?tipus=com

• Població de totes les entitats territorials de Catalunya que contenen "ab" en format JSON

  https://api.idescat.cat/pob/v1/geo.json?q=ab

Per conèixer els codis de resposta HTTP retornats i els formats suportats per qualsevol servei, consulteu l'apartat 2 de les APIs de l'Idescat. A més d'aquests formats generals, l'operació sug també suporta el format text (".txt").

2.1. Operació cerca

L'operació cerca utilitza, per descriure els resultats, l'estàndard Atom enriquit amb elements de l'estàndard OpenSearch i elements basats en l'estàndard estadístic SDMX.

2.1.1. Elements de l'estàndard OpenSearch

L'estàndard OpenSearch permet enriquir l'estàndard Atom per descriure adequadament el resultat d'una cerca. Consulteu la documentació d'aquests estàndards per conèixer l'estructura de la resposta de l'operació cerca: aquí només es documenten alguns elements que tenen un ús especial.

2.1.1.1. subtitle

L'operació cerca utilitza l'element opcional subtitle (fill de l'element feed) amb un text referit al resultat destacat, si n'hi ha (vegeu l'apartat 1.2.2.2. Filtre selec).

Ex. 6: Element subtitle

<subtitle xml:lang="ca">
   Resultat destacat: Sant Adrià, entitat singular (Tremp) amb 4 habitants (01.01.2008)
</subtitle>

2.1.1.2. category

L'operació cerca classifica els diferents resultats (entry) amb l'element category. Al servei de Cerca de població, aquest element pot tenir els valors de l'atribut term següents:

Tipus d'entitat territorial:

• CAT: Catalunya
• PROV: Província
• ATP: Àmbit territorial de planificació del Pla territorial general de Catalunya
• COM: Comarca
• MUN: Municipi
• EC: Entitat col·lectiva de població
• ES: Entitat singular de població
• NP: Nucli de població
• DIS: Disseminat de població

Proximitat de la denominació de l'entitat amb el text cercat:

• sim0
• sim1
• sim2

Consulteu l'apartat 1.2.2.1. Filtre sim per a una explicació d'aquests tres valors possibles.

Resultat destacat:

• selec: Indica que aquella és l'entitat territorial destacada. Pot aparèixer una vegada o cap.

Ex. 7: Element category

<category term="sim1"/>
<category term="MUN"/>

2.1.1.3. content

L'element content de cada entry s'utilitza per incorporar a cada resultat de la cerca un text en l'idioma escollit, amb el tipus i el nombre d'habitants de l'entitat.

Ex. 8: Element content

<content xml:lang="ca">Municipi: 33.761 hab.</content>

2.1.1.4. link

Alguns resultats (entry) poden incorporar un enllaç per ampliar la informació de l'entitat territorial. Amb aquesta finalitat, s'utilitza l'element link.

Ex. 9: Element link

<link type="text/html" href="https://www.idescat.cat/emex/?id=08194"/>

2.1.2. Elements basats en l'estàndard SDMX

Per encapsular els resultats estadístics, cada entry de l'estàndard Atom s'ha ampliat amb elements de l'estàndard SDMX.

Ex. 10: Resultats estadístics

<cross:DataSet>
	<cross:Section AREA="080018" TIME_PERIOD="2009-01-01" FREQ="A" UNIT_MULT="0" DECIMALS="0">
		<cross:Obs SEX="M" OBS_VALUE="5974" OBS_STATUS="A"/>
		<cross:Obs SEX="F" OBS_VALUE="5547" OBS_STATUS="A"/>
		<cross:Obs SEX="T" OBS_VALUE="11521" OBS_STATUS="A"/>
	</cross:Section>
</cross:DataSet>

Com es pot veure a l'exemple anterior, el codi de l'entitat territorial s'expressa com a valor de l'atribut AREA, el període de referència com a valor de l'atribut TIME_PERIOD i el nombre d'habitants per sexe com a valor de l'atribut OBS_VALUE.

2.2. Operació sug

Per descriure els resultats, l'operació sug utilitza l'estàndard OpenSearch Suggestions, que especifica una resposta en format JSON. Aquesta mateixa estructura s'utilitza en la resposta en format PHP serialitzat.

Ex. 11: Sortida de l'operació sug per a la cerca "ab", en format JSON

["ab",["Abadals, els","Abella","Abella d'Adons","Abella de la Conca","Abella, l'","Abrera"]]

La resposta en format XML inclou la mateixa informació estructurada d'acord amb l'estàndard XML Search Suggestions Format (a vegades anomenat OpenSearch SearchSuggest2).

Ex. 12: Sortida de l'operació sug per a la cerca "ab", en format XML

<SearchSuggestion version="2.0" xmlns="http://opensearch.org/searchsuggest2">
   <Query xml:space="preserve">ab</Query>
   <Section>
	  <Item>
	     <Text xml:space="preserve">Abadals, els</Text>
	  </Item>
	  <Item>
	     <Text xml:space="preserve">Abella</Text>
	  </Item>
	  <Item>
	     <Text xml:space="preserve">Abella d'Adons</Text>
	  </Item>
	  <Item>
	     <Text xml:space="preserve">Abella de la Conca</Text>
	  </Item>
	  <Item>
	     <Text xml:space="preserve">Abella, l'</Text>
	  </Item>
	  <Item>
	     <Text xml:space="preserve">Abrera</Text>
	  </Item>
   </Section>
</SearchSuggestion>

Per conveniència, també s'ofereix la resposta en format text, amb els resultats separats per salts de línia.

Ex. 13: Sortida de l'operació sug per a la cerca "ab", en format text

Abadals, els
Abella
Abella d'Adons
Abella de la Conca
Abella, l'
Abrera

2.3. Errors

Les APIs de l'Idescat utilitzen codis de resposta normalitzats per indicar si la petició ha tingut èxit o si ha fracassat.