Gestionar sus establecimientos
La POIs API le permite alimentar y gestionar su propia base de datos de establecimientos, haciendo que las búsquedas sean personalizables según sus necesidades. Todos los datos creados estarán vinculados al client_ID del usuario que realizó la adición/edición y sólo podrán ser consultados por dicho usuario.
- Cómo registrar y editar un nuevo establecimiento
- Cómo consultar un establecimiento registrado
- Cómo consultar la base de datos de establecimientos
- Cómo consultar las categorías y subcategorías disponibles
- Cómo comprobar los estados, ciudades y barrios de los establecimientos registrados
Cómo registrar y editar un nuevo establecimiento
La adición y actualización de establecimientos se realiza a través del siguiente endpoint (método POST):
Los siguientes parámetros son necesarios para la inclusión o actualización:
id– String con el identificador único del establecimiento. Si el ID ya está registrado, el punto de interés se actualizará con la información enviada;name– String para introducir el nombre del establecimiento;category– Categoría a la que pertenece el establecimiento;subCategory– Subcategoría en la que se encuadra el establecimiento;active– Valor booleano para indicar si el registro está activo o no (los registros inactivos no serán
devueltos en las búsquedas);address– Objeto con datos de dirección:street– String para introducir la dirección;number– String para el número de establecimiento;district– (Opcional) String para el barrio;city– String para la ciudad;state– String para el estado;zipcode– String para el código postal;point– Array con las coordenadas del establecimiento:latitude– Coordenada de latitud en grados decimales;longitude– Coordenada de longitud en grados decimales;
tags– (Opcional) Array de strings con «tags», o etiquetas, para identificar el tipo de establecimiento con categorías personalizadas;phones– (Opcional) Array de strings para los números de teléfono de contacto;additionalInfo– (Opcional) Objeto con información adicional sobre el punto. Las propiedades deben estar en formato de string en el patrón"key":"value".
Nota: Para ver las categorías y subcategorías disponibles para consulta y registro, simplemente realice una solicitud a los siguientes endpoints (método GET) https://api.maplink.global/place/v1/places/category y https://api.maplink.global/place/v1/places/subcategory
Si necesita actualizar un registro existente, sólo tiene que volver a enviar la solicitud indicando el identificador único con todos los parámetros requeridos y los datos actualizados.
El body de la solicitud debe seguir la siguiente estructura:
{
"id": "77",
"active": true,
"name": "Restaurante Dummy",
"category": "ALIMENTOS_E_BEBIDAS",
"subCategory": "RESTAURANTES",
"address": {
"street": "Praça Tiradentes",
"number": "23",
"city": "Rio de Janeiro",
"state": "RJ",
"zipcode": "20060-070",
"point": {
"latitude": -22.90741716416432,
"longitude": -43.182738139927416
}
},
"phones": [
"(21) 91234-5678"
],
"clientId": "maplink",
"tags": [
"Restaurante",
"Alimento"
],
"additionalInfo": {
"Se abre el fin de semana": "Sí"
}
}
Cómo consultar un establecimiento registrado
Para consultar todos los establecimientos registrados, basta con realizar una solicitud GET al siguiente endpoint, donde el término {{placeId} } debe sustituirse por el ID del establecimiento que desee:
Cómo consultar la base de datos de establecimientos
Para consultar todos los establecimientos registrados, basta con realizar una solicitud GET al siguiente endpoint:
Puede filtrar los resultados de la consulta mediante parámetros en la URL. Están disponibles los siguientes filtros:
city– Filtrar resultados por ciudad;district– Filtre los resultados por barrio o distrito;state– Filtrar resultados por estado;tag– Filtrar resultados por etiqueta;center– Coordenadas de referencia para la búsqueda de resultados. Formato:center=-23.552088765,-46.6341653162;radius– Especifica el radio de búsqueda, en metros, desde el punto central establecido encenter.
También puede hojear los resultados con los siguientes parámetros:
offset– Índice del primer valor;limit– Número de resultados por página, con un límite de 100.
En el ejemplo siguiente, tenemos 20 establecimientos registrados y queremos paginar los resultados, de forma que cada página contenga 10 establecimientos. Para consultar la primera página tendríamos:
https://api.maplink.global/place/v1/places?offset=0&limit=10
Para la segunda página tendríamos https://api.maplink.global/place/v1/places?offset=9&limit=10 y así sucesivamente.
Cómo consultar las categorías y subcategorías disponibles
Para ver una lista de todas las categorías disponibles para el registro, basta con hacer una solicitud GET al siguiente endpoint:
Para consultar las subcategorías, utilice el siguiente endpoint, también con el método GET:
Cómo comprobar los estados, ciudades y barrios de los establecimientos registrados
Puede consultar los estados, ciudades o barrios donde hay establecimientos registrados en la base de datos.
Consultar los Estados
Para consultar los estados en los que hay establecimientos registrados, basta con hacer una petición GET al siguiente endpoint:
El retorno vendrá en formato json, con un array que contiene las siglas de los estados donde hay establecimientos registrados, como se muestra en el siguiente ejemplo:
[
"RJ",
"SP"
]
Consultar ciudades
Para consultar las ciudades en las que hay establecimientos registrados, basta con hacer una petición GET al endpoint que figura a continuación, donde el término {{state}} debe sustituirse por el estado deseado:
- https://api.maplink.global/place/v1/places/state/{{state} }/ciudades – GET
El resultado vendrá en formato json, con una matriz que contiene las ciudades del estado solicitado en las que hay establecimientos registrados, como se muestra en el siguiente ejemplo:
[
"São Paulo",
"Ribeirão Preto",
"Campinas"
]
Consultar a los vecinos
Por último, para consultar los barrios donde hay establecimientos registrados, basta con hacer una petición GET al endpoint que figura a continuación, donde el término {{state}} debe sustituirse por el estado deseado y el término {{city}} por la ciudad:
El retorno vendrá en formato json, con un array que contendrá los barrios de la ciudad y estado solicitados en los que hay establecimientos registrados, como se muestra en el siguiente ejemplo:
[
"Sé Bela Vista",
"Bom Retiro",
"Cambuci",
"Aricanduva",
]
