Population search. API

1.1. Anatomy of requests

All requests must specify the service, version, operation and format. Version and operation are specific characteristics to each service. As well as the general response formats of Idescat's APIs, for reasons of convenience this service supports the text format in the sug operation. For more information, please consult the section Anatomy of requests in the general documentation of Idescat's APIs.

1.1.1. Service identifier and version

The identifier of this service is pob.

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

1.1.2. Operations

It allows two types of operation:

• cerca: Returns results of a search by name of territorial entity with information on its population. See section 1.2..

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

• sug: Returns the list of territorial entities that start with characters specified. See section 1.2..

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

1.2. Specific parameters

The specific parameters ("variables") make it possible to select the information that will be returned by a certain operation of the Indicators of the day service. They can be specified as individual parameters or in a single parameter p (compact form). In this documentation, the compact form is always used.

To find out the general parameters available for any service, consult the Idescat's APIs documentation.

1.2.1. Specific parameters that are common to all the operations

1.2.1.1. q filter

Both the cerca operation and the sug operation enable the selection of the territorial entities included in the response depending on its name using the q parameter. The meaning of this parameter varies depending on the operation.

• Operation cerca: Selects territorial entities that contain the specified chain of characters. It is an optional parameter.
• Operation sug: Selects territorial entities that start with the specified chain of characters. It is an optional parameter, but if there is none or the value has less than two characters, it does not return a result.

Ex. 1: List of territorial entities that start with "ab", separated by line feeds

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

1.2.1.2. tipus filter

Both the cerca operation and the sug operation enable selection of the territorial entities that include the response in accordance with the following typology:

• cat: Catalonia
• prov: Provinces
• com: Counties
• mun: Municipalities
• ec: Collective entities
• es: Singular entities
• np: Population nucleuses
• dis: Scattered populations (this value may not give any result because, at least at the time when this documentation was written, Catalonia had no scattered entities with a specific name)

These values can be linked separated by commas. By default, tipus is equal to cat,prov,com,mun,ec,es,np,dis.

Ex. 2: List of municipalities and population nucleuses that start with "ab", in text format

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

Ex. 3: Population of all the counties of Catalonia, in XML format

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

1.2.2. Specific parameters of the cerca operation

1.2.2.1. sim filter

The results of the cerca operation are associated to a category of similitude with the q chain being searched. The sim parameter enables filtration of the results depending on this similitude:

• 0: Only returns the territorial entities whose name coincides (not case sensitive and ignoring accents) with the one specified in q. It should be considered that the name used applies the official standards for the Catalan language in relation to the articles that accompany place names in a list, whereby, these are written to the right of the place name in small case and after a comma, in order to respect alphabetical order. This standard is valid for all types of article, whether normal, with an apostrophe or in the salat forms (for example, «Agaró, s'»).
• 1: Only returns the territorial entities that contain the q chain specified as a word (or expression) and that are not included in the previous section.
• 2: Only returns the territorial entities that contain the q chain specified as a fragment and that are not included in the previous sections.

These values can be linked separated by commas. By default, sim is equal to 0,1,2.

Ex. 4: Population of the territorial entities called "abrera" or that contain this name, in JSON format

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

1.2.2.2. selec filter

In most cases, the API is able to suggest a highlighted result even if there is more than one territorial entity in the category of similitude 0 (see the section 1.2.2.1. sim filtro). To do so, it takes into account the typology of territorial entities (1.2.1.2. tipus filter), prioritising in this order:

• Municipalities
• Provinces
• Collective entities
• Singular entities
• Population nucleuses
• Scattered

The selec parameter makes it possible to simplify the response to contain only one result (or none).

• 1: the response only includes the highlighted result (if there is one).
• 0: the response includes all the results. This is the default value.

Ex. 5: Highlighted result for the search "abrera", in English and in JSON format with callback function ("f")

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

1.2.2.3. orderby parameter

The results are shown in order of proximity to the search made: name of the entity equal to text searched, name with the full word or expression searched and name that contains the text searched as an incomplete fragment. The orderby parameter enables determination of the order of the results within this general ordering. It admits the following values:

• tipus: The order of results prioritises the type of entity. This is the default value.
• nom: The results are ordered alphabetically depending on the name of the territorial entity.

1.2.2.4. posicio parameter

As some searches might return a very high number of results, the response does not always include them all. The posicio parameter enables determination of what will be the first result included in the response. By default, posicio is equal to zero (it returns results starting with the first).

1.3. Invocation without operation

For reasons of user-friendliness, this API accepts requests with a syntax that does not require the specification of operations (see the general documentation on Idescat APIs, section 1.4. Invocation without operation).

• List of territorial entities starting with "ab" in text format

  http://api.idescat.cat/pob/v1/geo.txt?sug=ab&lang=en

• Population of all counties of Catalonia in XML format

  http://api.idescat.cat/pob/v1/geo.xml?tipus=com&lang=en

• Population of all territorial entities in Catalonia that contain "ab" in JSON format

  http://api.idescat.cat/pob/v1/geo.json?q=ab&lang=en

To find out the HTTP response codes returned and the formats supported by any service, consult section 2 of Idescat's APIs. As well as these general formats, the sug operation also supports text format (".txt").

2.1. Operation cerca

The cerca operation used to describe the results is the Atom standard enriched with elements of the OpenSearch standard and elements based on the SDMX statistical standard.

2.1.1. Elements of the OpenSearch standard

The OpenSearch standard makes it possible to enrich the Atom standard to adequately describe the result of a search. See the documentation on these standards to find out about the structure of the cerca operation response: here we only document some elements with special uses.

2.1.1.1. subtitle

The cerca operation uses the optional element subtitle (child of the feed element) with a text referring to the highlighted result, if there is one (see the section 1.2.2.2. selec filter).

Ex. 6: subtitle element

<subtitle xml:lang="en">
   Highlighted result: Sant Adrià, singular entity (Tremp) with 4 inhabitants (01.01.2008)
</subtitle>

2.1.1.2. category

The cerca operation classifies the different results (entry) with the category element. In the Population search service, this element can have the following values of the term attribute:

Type of territorial entity:

• CAT: Catalonia
• PROV: Provincial
• ATP: Territorial area of the General territorial plan for Catalonia
• COM: County
• MUN: Municipality
• EC: Collective population entity
• ES: Singular population entity
• NP: Population nucleus
• DIS: Scattered population

Proximity of the name of the entity to the text searched:

• sim0
• sim1
• sim2

See the section 1.2.2.1. sim filter for an explanation of these three possible values.

Highlighted result:

• selec: Indicates that this is the highlighted territorial entity. Can appear once or never.

Ex. 7: category element

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

2.1.1.3. content

The content element of each entry is used to incorporate a text in the chosen language in each result of the search showing the type and the number of inhabitants of the entity.

Ex. 8: content element

<content xml:lang="en">Municipality: 33,761 inhab.</content>

2.1.1.4. link

Some results (entry) may incorporate a link to expand on the information on that territorial entity. The link element is used to do this.

Ex. 9: link element

<link type="text/html" href="http://www.idescat.cat/territ/BasicTerr?TC=3&amp;V0=1&amp;V1=08194&amp;lang=en"/>

2.1.2. Elements based on the SDMX standard

To encapsulate the statistical results, each entry in the Atom standard is extended using common elements of the SDMX standard.

Ex. 10: Statistical results

<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>

As shown in the previous example, the territorial entity's code is expressed as a value of the AREA attribute, the period of reference as a value of the TIME_PERIOD attribute and the number of inhabitants by sex as a value of the OBS_VALUE attribute.

2.2. Operation sug

The sug operation uses the standard OpenSearch Suggestions to describe the results, which specifies a response in JSON format. The same structure is used in the serialized PHP format.

Ex. 11: Output of the sug operation for the search "ab" in JSON format

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

The response in XML format includes the same information structured in accordance with the standard XML Search Suggestions Format (sometimes known as OpenSearch SearchSuggest2).

Ex. 12: Output of the sug operation for the search "ab" in XML format

<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>

For reasons of convenience, the response is also offered in text format, with the results separated by line feeds.

Ex. 13: Output of the sug operation for the search "ab" in text format

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

2.3. Errores

Idescat's APIs use standardised response codes to indicate whether the request has been successful or has failed.