Locations Management API

Este servicio de API, disponible en JavocSoft, Locations Management API (http://api.cl.javocsoft.es/), se trata de una API gratuita de uso general para poder manejar POIs y/ó localizaciones de una manera sencilla. Lo que nos permitirá es abstraernos de ciertas tareas tediosas así como facilitarnos la gestión de nuestras localizaciones o POIs.

El servicio permite:

  • Darse de alta, vía API (necesario un e-mail para la activación de usuario).
  • Localizaciones: alta, modificación, desactivación, activación y listado.
  • Obtener un mapa de Google Maps con las localizaciones ó con los clusters.
  • Clustering de localizaciones. Agrupación de los puntos o localizaciones por proximidad entre ellos y para con el usuario según localización especificada.

Los motivos para la creación de esta API han sido:

  1. Si estas creando una aplicación o un servicio y necesitas guardar localizaciones en base de datos para mostrarlas posteriormente pero no deseas ocuparte de todo esto, por ejemplo, en el caso de una aplicación, te ahorrarías tener que crear la parte servidora si solo la necesitas por las localizaciones. Además, al poseer cada localización de dos “idExternal”, se puede usar uno para asociarlo a un usuario, por ejemplo y el otro para otro uso interno.
  2. Otro motivo es ahorrarte el trabajo de “clustering”, es decir, abstraerse de la gestión de la agrupación de los puntos o localizaciones por proximidad entre ellos y para con el usuario, tarea un tanto compleja.
  3. Si necesitas mostrar un mapa en la aplicación o web con los puntos de interés, localizaciones o clusters, la API también te ahorra este trabajo ya que dispone de llamadas GET que devolverán dicho mapa HTML en base a unos parámetros.

Te invito a probar el servicio bien sea por curiosidad o por la necesidad de solventar uno de los puntos arriba indicados. Podeis fácilmente probar el servicio a través de la herramienta Postman. Tenéis la documentación de la API aquí.

Para finalizar, os dejo un EJEMPLO de registro y activación:

Para usar el servicio es necesario registrarse con un e-mail válido ya que se enviará la confirmación del servicio a dicho e-mail aunque la activación se pueda hacer también vía API.

Registro de usuario

Tipo llamada: POST
URL: http://api.cl.javocsoft.es/ws/api/lclustering/v1/client/add
Header: Content-type : application/json
Cuerpo de la petición : JSON

{
  "name": "My name",
  "tradeName": "My commercial name",
  "email": "myemail@mail.com",
  "telephone1": "telephone",
  "contactName": "name",
  "contactSurname": "surname",
  "contactPosition": "position",
  "contactEmail": "contactmail@mail.com",
  "contactTelephone1": "telephone",
  "contactTelephone2": "telephone",
  "countryCode": "en",
  "defaultLocale": "en",
  "details": "",
  "url": "http://www.javocsoft.es"
}Lenguaje del código: JSON / JSON con comentarios (json)

La respuesta sería:

{
  "result": {
    "id": 38,
    "name": "My name",
    "tradeName": "My commercial name",
    "email": "myemail@mail.com",
    "telephone1": "telephone",
    "mKey": "4d7cbad4d424d1680088e76a66ad5a51e275f390",
    "activationCode": "cb3f233a73b03b0ee423bf91446bbf40cde08508",
    "status": "NEW",
    "tsCreated": "2024-11-10 09:27:33",
    "contactName": "contact name",
    "contactSurname": "contact surname",
    "contactPosition": "position",
    "contactEmail": "contactmail@mail.com",
    "contactTelephone1": "telephone1",
    "contactTelephone2": "telephone2",
    "countryCode": "en",
    "defaultLocale": "en",
    "details": "",
    "url": "http://www.javocsoft.es",
    "activationEmailSent": true,
    "tsActivationEmailSent": "2017-12-20 09:27:35"
  },
  "success": true,
  "time": 1513758455768
}Lenguaje del código: JSON / JSON con comentarios (json)

Revisa siempre el código HTTP, si no hubo error, será siempre un 200. Aparte, si la petición fue bien, en el campo “success” del JSON se indicará “true”. En caso contrario, se devolverá el error con el código HTTP de error que corresponda, por ejemplo, si una vez registrado vuelves a tratar de registra el mismo cliente:

{
  "result": {
    "errorCode": 1002,
    "errorMessage": "Client already exists."
  },
  "success": false,
  "time": 1513758753655
}Lenguaje del código: JSON / JSON con comentarios (json)

Si todo fué bien, tendrás dos valores nuevos en el cliente:

  • “mKey“, esta es tu clave API para usar el servicio, solo será válida si activaste tu cuenta.
  • “activationCode“, usado para la activación de la cuenta ya que el cliente aún no esta activo como se puede comprobar en el campo “status” en donde se indica “NEW”.

Activación de usuario

Para activar la cuenta hay dos maneras:

  • Haciendo clic en el link en el correo electrónico que habrás recibido en el e-mail especificado.
  • A través de la propia API.

Si lo haces a través de la API, deberás usar el valor del campo “activationKey” devuelto en el registro tal que:

Tipo llamada: POST
URL: http://api.cl.javocsoft.es/ws/api/lclustering/v1/client/activate/activationCode

Si todo va bien la respuesta será:

{
  "result": {
    "id": 38,
    "name": "My name",
    "tradeName": "My commercial name",
    "email": "myemail@mail.com",
    "telephone1": "telephone",
    "mKey": "4d7cbad4d424d1680088e76a66ad5a51e275f390",
    "activationCode": "cb3f233a73b03b0ee423bf91446bbf40cde08508",
    "tsActivationCode": "2017-12-20 09:40:15",
    "status": "ACTIVE",
    "tsCreated": "2024-11-10 09:27:33",
    "contactName": "contact name",
    "contactSurname": "contact surname",
    "contactPosition": "position",
    "contactEmail": "contactmail@mail.com",
    "contactTelephone1": "telephone1",
    "contactTelephone2": "telephone2",
    "countryCode": "en",
    "defaultLocale": "en",
    "details": "",
    "url": "http://www.javocsoft.es",
    "activationEmailSent": true,
    "tsActivationEmailSent": "2017-12-20 09:27:35"
  },
  "success": true,
  "time": 1513759215297
}Lenguaje del código: JSON / JSON con comentarios (json)

Donde podremos ver que el estado ha cambiado a “ACTIVE”. En este punto ya podremos realizar peticiones a la API usando nuestra clave de la API.

Un saludo,