|Response Formats||xml, json, php,txt|
- 1. Request
- 1.1. Anatomy of requests
- 1.2. Specific parameters
- 1.3. Invocation without operation
- 2. Response
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.
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..
sug: Returns the list of territorial entities that start with characters specified. See section 1.2..
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
126.96.36.199. 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
/v1 /sug.txt ?p=q/ab
188.8.131.52. 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
- atp: Territorial area of the General territorial plan for Catalonia
- 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,atp,com,mun,ec,es,np,dis.
Ex. 2: List of municipalities and population nucleuses that start with "ab", in text format
/v1 /sug.txt ?p=q/ab ;tipus/mun,np
Ex. 3: Population of all the counties of Catalonia, in XML format
/v1 /cerca.xml ?p=tipus/com
1.2.2. Specific parameters of the cerca operation
184.108.40.206. 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
/v1 /cerca.json ?p=q/abrera ;sim/0,1
220.127.116.11. 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 18.104.22.168. sim filter). To do so, it takes into account the typology of territorial entities (22.214.171.124. tipus filter), prioritising in this order:
- Collective entities
- Singular entities
- Population nucleuses
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")
/v1 /cerca.json ?p=q/abrera ;selec/1 &callback=f &lang=en
126.96.36.199. 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.
188.8.131.52. 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
/v1 /geo.txt ?sug=ab &lang=en
- Population of all counties of Catalonia in XML format
/v1 /geo.xml ?tipus=com &lang=en
- Population of all territorial entities in Catalonia that contain "ab" in JSON format
/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
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.
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 184.108.40.206. selec filter).
Ex. 6: subtitle element
<subtitle xml:lang="en"> Highlighted result: Sant Adrià, singular entity (Tremp) with 4 inhabitants (01.01.2008) </subtitle>
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:
See the section 220.127.116.11. sim filter for an explanation of these three possible values.
- selec: Indicates that this is the highlighted territorial entity. Can appear once or never.
Ex. 7: category element
<category term="sim1"/> <category term="MUN"/>
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>
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="https://www.idescat.cat/emex/?id=08194&lang=en"/>
2.1.2. Elements based on 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"]]
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
Idescat's APIs use standardised response codes to indicate whether the request has been successful or has failed.