|Response Formats||xml, json, php,txt|
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.
The identifier of this service is pob.
It allows two types of operation:
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.
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.
/v1 /sug.txt ?p=q/ab
Both the cerca operation and the sug operation enable selection of the territorial entities that include the response in accordance with the following typology:
These values can be linked separated by commas. By default, tipus is equal to cat,prov,atp,com,mun,ec,es,np,dis.
/v1 /sug.txt ?p=q/ab ;tipus/mun,np
/v1 /cerca.xml ?p=tipus/com
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:
These values can be linked separated by commas. By default, sim is equal to 0,1,2.
/v1 /cerca.json ?p=q/abrera ;sim/0,1
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:
The selec parameter makes it possible to simplify the response to contain only one result (or none).
/v1 /cerca.json ?p=q/abrera ;selec/1 &callback=f &lang=en
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:
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).
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).
/v1 /geo.txt ?sug=ab &lang=en
/v1 /geo.xml ?tipus=com &lang=en
/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").
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 126.96.36.199. selec filter).
<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:
Proximity of the name of the entity to the text searched:
See the section 188.8.131.52. sim filter for an explanation of these three possible values.
<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.
<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.
<link type="text/html" href="https://www.idescat.cat/emex/?id=08194&lang=en"/>
<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.
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.
["ab",["Abadals, els","Abella","Abella d'Adons","Abella de la Conca","Abella, l'","Abrera"]]
<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.
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.