Búsqueda de población. API RSS

29.06.2017

La API de Búsqueda de población proporciona información de la población por sexo de cualquier entidad territorial de Cataluña.

La utilización de este servicio comporta la aceptación de las condiciones de uso de las API del Idescat.

Resumen
URI base https://api.idescat.cat/pob/v1/{operación}.{formato}[?parámetros]
Método HTTP GET
Formatos de la respuesta xml, json, php, txt
Versión 1.00 (20.05.2010)
Atajos Petición, Respuesta
Operaciones cerca, sug
Widgets que utilizan este servicio

1. Petición

1.1. Anatomía de las peticiones

Toda petición debe especificar obligatoriamente el servicio, la versión, la operación y el formato. Versión y operación son características específicas de cada servicio. Además de los formatos de respuesta generales de las API del Idescat, por conveniencia el servicio de Búsqueda de población soporta el formato texto en la operación sug. Para más información, consulte el apartado Anatomía de las peticiones en la documentación general de las API del Idescat.

1.1.1. Identificador del servicio y versión

El identificador de este servicio es pob.

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

1.1.2. Operaciones

Admite dos tipos de operaciones:

  • cerca: Devuelve resultados de una búsqueda por nombre de entidad territorial con información sobre su población. Véase el apartado 1.2..
    https://api.idescat.cat/pob/v1/cerca.{…}
  • sug: Devuelve la lista de entidades territoriales que comienzan por los caracteres especificados. Véase el apartado 1.2..
    https://api.idescat.cat/pob/v1/sug.{…}

1.2. Parámetros específicos

Los parámetros específicos ("variables") permiten escoger la información que devolverá una determinada operación del servicio de Indicadores al día. Se pueden especificar como parámetros individuales o en un único parámetro p (forma compacta). En esta documentación, se utiliza siempre la forma compacta.

Para conocer los parámetros generales disponibles para cualquier servicio, consulte la documentación de las API del Idescat.

1.2.1. Parámetros específicos comunes a todas las operaciones

1.2.1.1. Filtro q

Tanto la operación cerca como la operación sug permiten seleccionar las entidades territoriales que se incluirán en la respuesta según su denominación utilizando el parámetro q. El significado de este parámetro varía según la operación.

  • Operación cerca: Selecciona entidades territoriales que contengan la cadena de caracteres especificada. Es un parámetro opcional.
  • Operación sug: Selecciona entidades territoriales que comiencen con la cadena de caracteres especificada. Es un parámetro opcional, pero si no se especifica o su valor tiene menos de dos caracteres, no devolverá ningún resultado.
Ej. 1: Lista de entidades territoriales que comienzan por "ab", separadas por saltos de línea
https://api.idescat.cat/pob/v1/sug.txt?p=q/ab
1.2.1.2. Filtro tipus

Tanto la operación cerca como la operación sug permiten seleccionar las entidades territoriales que se incluirán en la respuesta de acuerdo con la tipología siguiente:

  • cat: Cataluña
  • prov: Provincias
  • atp: Ámbito territorial de planificación del Plan territorial general de Cataluña
  • com: Comarcas
  • mun: Municipios
  • ec: Entidades colectivas
  • es: Entidades singulares
  • np: Núcleos de población
  • dis: Diseminados (este valor puede no dar resultados porque, al menos en el momento de redactar esta documentación, no había en Cataluña ninguna entidad diseminada que tuviera un nombre específico)

Estos valores se pueden concatenar separados por comas. Por defecto, tipus es igual a cat,prov,atp,com,mun,ec,es,np,dis.

Ej. 2: Lista de municipios y núcleos de población que comienzan por "ab", en formato texto
https://api.idescat.cat/pob/v1/sug.txt?p=q/ab;tipus/mun,np
Ej. 3: Población de todas las comarcas de Cataluña, en formato XML
https://api.idescat.cat/pob/v1/cerca.xml?p=tipus/com

1.2.2. Parámetros específicos de la operación cerca

1.2.2.1. Filtro sim

Los resultados de la operación cerca tienen asociada una categoría de similitud con la cadena q buscada. El parámetro sim permite filtrar los resultados según esta similitud:

  • 0: Sólo se devuelven las entidades territoriales cuya denominación coincide con la especificada en q (ignorando mayúsculas y minúsculas y acentos). Debe tenerse en cuenta que la denominación utilizada aplica la normativa oficial de la lengua catalana según la cual los artículos que acompañan a topónimos en una lista se escriben a la derecha del topónimo en minúscula y después de una coma, para respetar la ordenación alfabética. Esta norma es válida para cualquier tipo de artículo normativo, ya sea normal, con apóstrofo o salado (por ejemplo, «Agaró, s'»).
  • 1: Sólo se devuelven las entidades territoriales que contienen la cadena q especificada como palabra (o expresión) y no están incluidas en el apartado anterior.
  • 2: Sólo se devuelven las entidades territoriales que contienen la cadena q especificada como fragmento y no están incluidas en los apartados anteriores.

Estos valores se pueden concatenar separados por comas. Por defecto, sim es igual a 0,1,2.

Ej. 4: Población de las entidades territoriales que se denominan "abrera" o contienen este nombre, en formato JSON
https://api.idescat.cat/pob/v1/cerca.json?p=q/abrera;sim/0,1
1.2.2.2. Filtro selec

En la mayoría de casos, la API es capaz de sugerir un resultado destacado incluso cuando hay más de una entidad territorial en la categoría de similitud 0 (véase el apartado 1.2.2.1. Filtro sim). Para ello, tiene en cuenta la tipología de entidades territoriales (véase el apartado 1.2.1.2. Filtro tipus), priorizándolas en este orden:

  • Municipios
  • Provincias
  • Entidades colectivas
  • Entidades singulares
  • Núcleos de población
  • Diseminados

El parámetro selec permite simplificar la respuesta para que contenga sólo un resultado (o ninguno).

  • 1: La respuesta sólo incluye el resultado destacado (si existe).
  • 0: La respuesta incluye todos los resultados. Es el valor por defecto.
Ej. 5: Resultado destacado para la búsqueda "abrera", en inglés y en formato JSON con función de devolución ("f")
https://api.idescat.cat/pob/v1/cerca.json?p=q/abrera;selec/1&callback=f&lang=en
1.2.2.3. Parámetro orderby

Los resultados se muestran ordenados por proximidad con la búsqueda efectuada: nombre de la entidad igual al texto buscado, nombre con la palabra o expresión completa buscada y nombre que contiene el texto buscado como fragmento no completo. El parámetro orderby permite determinar la ordenación de los resultados dentro de esta ordenación general. Admite los valores siguientes:

  • tipus: La ordenación de los resultados prioriza el tipo de entidad. Es el valor por defecto.
  • nom: Los resultados se ordenan alfabéticamente según el nombre de la entidad territorial.
1.2.2.4. Parámetro posicio

Como algunas búsquedas pueden dar un número muy elevado de resultados, la respuesta no siempre los incluirá todos. El parámetro posicio permite determinar cuál es el primer resultado incluido en la respuesta. Por defecto, posicio es igual a cero (se devuelven resultados comenzando por el primero).

1.3. Invocación sin operación

Por razones de amigabilidad, esta API admite peticiones con una sintaxis que no requiere especificar operaciones (véase, en la documentación general de las API del Idescat, el apartado 1.4. Invocación sin operación).

  • Lista de entidades territoriales que empiezan con "ab" en formato texto
    https://api.idescat.cat/pob/v1/geo.txt?sug=ab&lang=es
  • Población de todas las comarcas de Cataluña en formato XML
    https://api.idescat.cat/pob/v1/geo.xml?tipus=com&lang=es
  • Población de todas las entidades territoriales de Cataluña que contienen "ab" en formato JSON
    https://api.idescat.cat/pob/v1/geo.json?q=ab&lang=es

2. Respuesta

Para conocer los códigos de respuesta HTTP devueltos y los formatos soportados por cualquier servicio, consulte el apartado 2 de las API del Idescat. Además de estos formatos generales, la operación sug también soporta el formato texto (".txt").

2.1. Operación cerca

La operación cerca utiliza, para describir los resultados, el estándar Atom enriquecido con elementos del estándar OpenSearch y elementos basados en el estándar estadístico SDMX.

2.1.1. Elementos del estándar OpenSearch

El estándar OpenSearch permite enriquecer el estándar Atom para describir adecuadamente el resultado de una búsqueda. Consulte la documentación de estos estándares para conocer la estructura de la respuesta de la operación cerca: aquí sólo se documentan algunos elementos que tienen un uso especial.

2.1.1.1. subtitle

La operación cerca utiliza el elemento opcional subtitle (hijo del elemento feed) con un texto referido al resultado destacado, si existe (véase el apartado 1.2.2.2. Filtro selec).

Ej. 6: Elemento subtitle
<subtitle xml:lang="es">
   Resultado destacado: Sant Adrià, entidad singular (Tremp) con 4 habitantes (01.01.2008)
</subtitle>
2.1.1.2. category

La operación cerca clasifica los diferentes resultados (entry) con el elemento category. En el servicio de Búsqueda de población, este elemento puede tener los siguientes valores del atributo term:

Tipo de entidad territorial:

  • CAT: Cataluña
  • PROV: Provincia
  • ATP: Ámbito territorial de planificación del Plan territorial general de Cataluña
  • COM: Comarca
  • MUN: Municipio
  • EC: Entidad colectiva de población
  • ES: Entidad singular de población
  • NP: Núcleo de población
  • DIS: Diseminado de población

Proximidad de la denominación de la entidad con el texto buscado:

  • sim0
  • sim1
  • sim2

Consulte el apartado 1.2.2.1. Filtro sim para una explicación de estos tres valores posibles.

Resultado destacado:

  • selec: Indica la entidad territorial destacada. Puede aparecer una vez o ninguna.
Ej. 7: Elemento category
<category term="sim1"/>
<category term="MUN"/>
2.1.1.3. content

El elemento content de cada entry se utiliza para incorporar a cada resultado de la búsqueda un texto en el idioma seleccionado, con el tipo y el número de habitantes de la entidad.

Ej. 8: Elemento content
<content xml:lang="es">Municipio: 33.761 hab.</content>
2.1.1.4. link

Algunos resultados (entry) pueden incorporar un enlace para ampliar la información de la entidad territorial. Con esta finalidad, se utiliza el elemento link.

Ej. 9: Elemento link
<link type="text/html" href="https://www.idescat.cat/emex/?id=08194&amp;lang=es"/>

2.1.2. Elementos basados en el estándar SDMX

Para encapsular los resultados estadísticos, cada entry del estándar Atom se ha ampliado con elementos del estándar SDMX.

Ej. 10: Resultados estadísticos
<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>

Como se puede ver en el ejemplo anterior, el código de la entidad territorial se expresa como valor del atributo AREA, el periodo de referencia como valor del atributo TIME_PERIOD y el número de habitantes por sexo como valor del atributo OBS_VALUE.

2.2. Operación sug

Para describir los resultados, la operación sug utiliza el estándar OpenSearch Suggestions, que especifica una respuesta en formato JSON. Esta misma estructura se utiliza en la respuesta en formato PHP serializado.

Ej. 11: Salida de la operación sug para la búsqueda "ab", en formato JSON
["ab",["Abadals, els","Abella","Abella d'Adons","Abella de la Conca","Abella, l'","Abrera"]]

La respuesta en formato XML incluye la misma información estructurada de acuerdo con el estándar XML Search Suggestions Format (a veces denominado OpenSearch SearchSuggest2).

Ex. 12: Salida de la operación sug para la búsqueda "ab", en formato 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>

Por conveniencia, también se ofrece la respuesta en formato texto, con los resultados separados por saltos de línea.

Ej. 13: Salida de la operación sug para la búsqueda "ab", en formato texto
Abadals, els
Abella
Abella d'Adons
Abella de la Conca
Abella, l'
Abrera

2.3. Errores

Las API del Idescat utilizan códigos de respuesta normalizados para indicar si la petición ha tenido éxito o si ha fracasado.

Usted está aquí: