geoapi.es-docs

Documentación para la API de GeoAPI.es

Ésta es la documentacion generica para la API de GeoAPI.es. Se recomienda la lectura en conjunto con la documentación específica de la librería que se desee utilizar.

Notas

• Todos los datos se envían en UTF-8.
• Existe una limitación de 1 segundo entre petición y petición en el modo sandbox.
• Recomendamos utilizar POSTMAN (Extensión de Chrome) para realizar pruebas.
• Recomendamos utilizar redis o memcached para no malgastar peticiones.

Cómo funciona

El funcionamiento básico de GeoAPI consiste en lanzar peticiones GET al endpoint, el cual es http://apiv1.geoapi.es/ si no se indica algun otro endpoint de manera explícita, pasando una serie de parámetros en cada petición. Dichos parámetros sirven para, por ejemplo, filtrar o concretar una búsqueda.

Ejemplo de petición:

http://apiv1.geoapi.es/poblaciones?CPRO=22&CMUM=907&type=JSON&key=&sandbox=1

Parámetros de configuración

Hay varios parámetros de configuración que indican a la API cómo debe actuar, así como los datos de usuario que debe usar.

• url - Indica la URL del endpoint. http://apiv1.geoapi.es/ por defecto.
• type - Indica el tipo de respuesta, a elegir entre JSON o XML. Si no se indica nada, se usará JSON.
• key - La API Key que se usará para hacer las peticiones. Puede tener un valor nulo ('') si se activa el modo sandbox. Si no se especifica, se enviara ''.
• sandbox - Puede ser 0 (desactivado, por defecto) o 1 (activado). En caso de activar el modo sandbox, no se requerirá una API Key. De ser enviada una API Key, no se descontarán peticiones de la misma. Ten en cuenta que en modo sandbox las letras de los resultados pueden estar mezcladas.

Dichos parámetros se establecen con el método setConfig de cada librería.

Parámetros de consultas

Además de los parámetros de configuración, la API permite el uso de varios parámetros a mayores, que especifican qué tipo de resultado se desea obtener.

Parametro	Descripcion
CCOM	ID de comunidad
CPRO	ID de provincia
CMUM	ID de municipio
NENTSI50	Nombre de población
CUN	ID de núcleo
CPOS	Código postal

Estos parámetros se usan con los métodos de consultas de cada librería.

Orden de los datos

Cada método de cada una de las librerías ofrece acceso rápido a ciertas partes de la base de datos. Todos los datos están ordenados de tal manera para que sea posible acceder a cualquier información almacenada, sin conocer previamente ningún ID.

Así por ejemplo, para obtener una lista de todas las comunidades y sus IDs, haremos una consulta a la API sin especificar parámetros.

Una vez obtenidos los IDs de las comunidades, podemos enviar otra petición a la API, pasando como parámetro solo el ID de aquella comunidad cuyas provincias queramos obtener.

De la misma manera procederemos con los municipios, poblaciones, núcleos y códigos postales hasta llegar a las calles, que es el nivel de detalle más alto.

Métodos genéricos

Todas las librerías tienen los mismos métodos, por tanto cubriremos sus nombres y sus parámetros aquí. Así evitamos duplicar información.

Un método tiene el mismo nombre que la parte final (acción) de cualquier URL usada para hacer una petición a GeoAPI, entre el ultimo / y justo antes de los parámetros. Por ejemplo:

URL	Método
apiv1.geoapi.es/comunidades	comunidades()
apiv1.geoapi.es/poblaciones?CPRO=22&CMUM=907	poblaciones()

Listado completo de acciones y sus parámetros

Todos los parámetros son obligatorios, al menos que se especifique lo contrario.

Accion	Parámetros	Descripcion
calles	CPRO, CMUM, CUN, CPOS	Devuelve un listado completo de todas las calles
comunidades		Devuelve un listado de todas las comunidades
cps	CPRO, CMUM, CUN	Devuelve un listado de todos los codigos postales
municipios	CPRO	Devuelve un listado de todos los municipios
nucleos	CPRO, CMUM, NENTSI50	Devuelve un listado de los núcleos de un municipio. Suele haber, aunque no se limita, 1 núcleo que representa el municipio en sí y un núcleo *DISEMINADO* que representa áreas, caminos, carreteras, fincas, etc, más alejadas del municipio, pero que están dentro de los límites territoriales del mismo e incluso llegan a compartir código postal con éste.
poblaciones	CPRO, CMUM	Devuelve un listado de todas las poblaciones
provincias	CCOM	Devuelve un listado de una o de todas las provincias. CCOM no es obligatorio.
qcalles	QUERY	Ésta es una acción especial que acepta cadenas de texto y realiza búsquedas basándose en los nombres de las calles. Es decir, es una búsqueda libre para calles.

Tipos de respuesta

Las respuestas pueden ser del tipo JSON o XML, segun lo establecido en la configuración de la librería que se esté usando o el parámetro que se envíe (si se prefiere usar la API sin usar las librerías proporcionadas).

Cubriremos las posibles respuestas en el formato JSON, aunque para XML son las mismas.

• Datos

  Una respuesta normal de la API tiene el siguiente formato:

  //
  {
      "update_date": "2015.06",
      "size": 42,
      "data": [
          {}, {}, {}, {}...
      ]
  }

  Es decir, un objeto con las siguientes claves:

  • update_date - Especifica la fecha (año y mes) en la cual los datos devueltos fueron actualizados por última vez.
  • size - Contiene el número de elementos contenidos en data.
  • data - Es un array de objetos. Dependiendo de la petición enviada, cada objeto tendra unos datos u otros.

• Avisos

  Además de los datos anteriores, la API puede embeber otra clave en la respuesta. Esta clave se llama warning y contiene una cadena de texto con cualquier aviso que la API decida que debe ser devuelto, como por ejemplo que el modo sandbox está activado.

• Errores

  Además de los datos anteriores, la API puede embeber otra clave en la respuesta. Esta clave se llama error y contiene una cadena de texto con cualquier error que la API decida que debe ser devuelto, como por ejemplo que no quedan peticiones en la API Key que se está usando.