Cerca amb autocompletar
URL: https://eines.icgc.cat/geocodificador/autocompletar (GET)
Descripció
L'operació autocompletar obté les dades i la ubicació d’una adreça o topònim sense necessitat de completar totes les dades d’identificació: a mesura que es va introduint el text a la caixa de cerca, s’envien peticions a autocompletar, amb la finalitat de trobar respostes de forma ràpida.
És imprescindible indicar el text a cercar en el paràmetre text.
El resultat s'obté en format GeoJSON.
En la integració en altres aplicacions, es recomana combinar autocompletar i cerca:
- a mesura que l'usuari va teclejant el text a cercar, enviar peticions a autocompletar, amb la finalitat de trobar respostes de forma ràpida.
- un cop s'ha completat el text, si les respostes proporcionades per autocompletar no són suficients, es pot prèmer la tecla [Intro] i fer una petició a l'operació de cerca completa.
Donat que les peticions a autocompletar generalment responen directament a l'entrada de text per part de l'usuari, cal tenir en compte la velocitat d'escriptura amb l'objectiu de no col·lapsar les peticions.
També és necessari tenir en compte que les respostes poden ser asíncrones i no ser respostes en el mateix ordre en que es varen enviar.
Exemple
| Exemple petició | Exemple resposta GeoJSON |
|---|---|
| https://eines.icgc.cat/geocodificador/autocompletar?text=can%C2%A0mass&layers=tops&size=1 | Imatge
|
Construcció de la consulta i paràmetres d'entrada
La petició a l'API es construeix a partir de la URL https://eines.icgc.cat/geocodificador/autocompletar, seguit del signe ? i de la seqüència de paràmetres, separats pel signe &.
Els paràmetres són els següents:
text: conté el text a cercar. És un paràmetre obligatori.
És important tenir en compte que, en el cas de cerca d'adreces postals, cal separar el portal i el nom del municipi amb una coma, seguint el format: nom_de_carrer portal, municipi
Exemple: https://eines.icgc.cat/geocodificador/autocompletar?text=nou 10,girona.
layers: s'utilitza per filtrar els tipus d'element a cercar
Es poden diferenciar els tipus de dades a cercar indicant el paràmetre layers, amb els valors següents:
- address: adreces postals.
- tops: tots els topònims.
topo_tipus_id: topònims del tipus id, on id és una cadena amb nombres entre 1 i 22, amb el 0 a l'esquerra pels menors de 10. Per exemple: topo_tipus_01 per cercar 'Caps de municipi'. La taula amb els tipus de topònim i els seus identificadors es pot consultar a Taula topònims.
Es poden indicar els valors següents per segregar els topònims en dos grups:
- topo1: topònims referents a agrupacions de població (municipis, caps de municipi, entitats de població, disseminats i barris).
- topo2: resta de topònims.
Exemple, per trobar topònims amb el nom 'Riera de Gaià': https://eines.icgc.cat/geocodificador/autocompletar?text=riera%20de%20gaia&layers=topo1,topo2.
size: s'utilitza per a definir el nombre màxim de resultats.
Per defecte, es retornen fins a 10 resultats de cada un dels tipus indicats a layers. Es pot indicar un nombre diferent amb el paràmetre size. El valor màxim és 40.
Per exemple, per a trobar un únic topònim: https://eines.icgc.cat/geocodificador/autocompletar?text=riera%20de%20gaia&layers=topo1&size=1.
boundary.rect.min_lon, boundary.rect.min_lat, boundary.rect.max_lon i boundary.rect.max_lat: per cercar en una àrea rectangular.
Es pot limitar espaialment la cerca indicant les coordenades latitud i longitud d'un rectangle amb aquests paràmetres.
boundary.circle.lon, boundary.circle.lat, boundary.circle.radius: per cercar en una àrea circular.
Es pot limitar espaialment la cerca indicant les coordenades d'un cercle amb els paràmetres boundary.circle.lon i boundary.circle.lat (coordenada central de referència) i el paràmetre boundary.circle.radius (radi en km).
focus.point.lat, focus.point.lon: priorització de resultats per proximitat.
Per prioritzar els resultats més propers a unes coordenades cal indicar-les amb aquests paràmetres.
com: per filtrar per comarca.
El paràmetre com permet especificar el nom de la comarca o el seu identificador. Es pot consultar el llistat de comarques a https://www.idescat.cat/codis/?id=50&n=10.
Exemples:
https://eines.icgc.cat/geocodificador/autocompletar?text=biblioteca&com=girones (indicant el nom de comarca).
https://eines.icgc.cat/geocodificador/autocompletar?text=biblioteca&mun=20 (indicant identificador de comarca).
mun: per filtrar per municipi.
El paràmetre mun permet especificar el nom del municipi o el seu identificador. Es pot consultar el llistat de municipis a https://www.idescat.cat/codis/?id=50&n=9.
Exemples:
https://eines.icgc.cat/geocodificador/autocompletar?text=biblioteca&mun=girona (indicant el nom de municipi).
https://eines.icgc.cat/geocodificador/autocompletar?text=biblioteca&mun=170792 (indicant identificador de municipi).
Taula dels paràmetres d'entrada
| Paràmetre | Tipus | Obligatori | Descripció | Valor per defecte | Exemple | |
|---|---|---|---|---|---|---|
| text | cadena de text | Si | Text a cercar | - | Riera de Sallent | |
| focus.point.lat | número de punt flotant | No | Per prioritzar els resultats propers al punt indicat | Latitud del punt per prioritzar les respostes | - | 41.430371882652814 |
| focus.point.lon | número de punt flotant | No | Longitud del punt per prioritzar les respostes | - | 1.8566894531250002 | |
| layers | cadena de text | No | El paràmetre layers permet definir els tipus d’elements a cercar i pot prendre els valors següents separats per comes:
Els resultats es mostren ordenats segons l'ordre dels elements indicats al paràmetre layers. | topo1,topo2, address | topo1,topo2, address | |
| size | enter | Nom | Nombre de resultats | 10 | 5 | |
| boundary.circle.lon | número de punt flotant | No | Per cercar resultats dins un cercle | Longitud del centre del cercle de cerca | - | 2.81233 |
| boundary.circle.lat | número de punt flotant | No | Latitud del centre del cercle de cerca | - | 41.98000 | |
| boundary.circle.radius | número de punt flotant | No | Radi del cercle de cerca (en km) | - | 190 | |
| boundary.rect.min_lon | número de punt flotant | No | Per cercar resultats dins un rectangle | Longitud de l'extrem inferior del rectangle de cerca | - | 2.694053649902344 |
| boundary.rect.min_lat | número de punt flotant | No | Latitud de l'extrem inferior del rectangle de cerca | - | 41.909303728668824 | |
| boundary.rect.max_lon | número de punt flotant | No | Longitud de l'extrem superior del rectangle de cerca | - | 2.911033630371094 | |
| boundary.rect.max_lat | número de punt flotant | No | Latitud de l'extrem superior del rectangle de cerca | - | 42.01142264969458 | |
| com | cadena de text | No | Identificador d'una comarca, dins la que vol restringir la cerca Pot ser el nom total o parcial de la comarca (sempre que l'identifiqui unívocament) o el seu l'identificador. Es pot consultar el llistat de comarques a https://www.idescat.cat/codis/?id=50&n=10 | Cap | 01 | |
| mun | cadena de text | No | Identificador d'un municipi, dins el que vol restringir la cerca Pot ser el nom total o parcial del municipi (sempre que l'identifiqui unívocament) o el seu l'identificador. Es pot consultar el llistat de municipis a https://www.idescat.cat/codis/?id=50&n=9 | Cap | 080018 | |
Taula dels paràmetres de sortida
Es retornen els resultats en format GeoJSON.
L'element features.properties té els camps descrits a la taula següent:
| Camp | Descripció | Aplicable als elements |
|---|---|---|
| layer | Tipus d'element trobat. Els valors possibles són els indicats al paràmetre layers d'entrada | Tots |
| etiqueta | Agregació de camps:
| Tots |
| municipi | Municipi assignat En alguns topònims, no hi ha un municipi assignat i pren el valor "-" | Tots |
| comarca | Comarca En alguns topònims , no hi ha una comarca assignada i pren el valor "-" | Tots |
| llogaret | Llogaret | Adreces |
| portal | Portal de l'adreça | Adreces |
| nom | Nom de carrer o d'edificació aïllada Nom del topònim | Tots |
| codi_postal | Codi postal | Adreces |
| distancia | Distància en quilòmetres al punt indicat amb els camps focus.point.lat, focus.point.lon | Tots |
| addendum.origen | Escala origen de les coordenades | Topònims |
| addendum.zoom | Nivell de zoom òptim | Topònims |
| addendum.tipus | Tipus de topònim (veure Tipus de topònims) | Topònims |
| addendum.id_tipus | Identificador tipus de topònim | Topònims |
| addendum.municipis_extra | Resta de municipis assignats | Topònims |
| addendum.bbox | Coordenades geogràfiques del rectangle contenidor del carrer | Adreces |
| addendum.bbox_utm | Coordenades UTM del rectangle contenidor del carrer | Adreces |
Exemples de sortida segons tipus de layer:
