A POIs API permite alimentar e gerenciar uma base própria de estabelecimentos, tornando as pesquisas personalizáveis conforme a sua demanda. Todos os dados criados ficarão vinculados ao client_ID do usuário que realizou a inclusão/edição e só poderão ser consultados pelo mesmo.

• Como cadastrar e editar um novo estabelecimento
• Como consultar um estabelecimento cadastrado
• Como consultar a base de estabelecimentos
• Como consultar as categorias e subcategorias disponíveis
• Como consultar estados, cidades e bairros dos estabelecimentos cadastrados

Como cadastrar e editar um novo estabelecimento

A inclusão e atualização de estabelecimentos é realizada através do endpoint a seguir (método POST):

• https://api.maplink.global/place/v1/places – POST

Os seguintes parâmetros são necessários para a inclusão ou atualização:

• id – String com o identificador único do estabelecimento. Caso o ID já esteja cadastrado, o ponto de interesse será atualizado com as informações enviadas;
• name – String para informar o nome do estabelecimento;
• category – Categoria em que se enquadra o estabelecimento;
• subCategory – Subcategoria em que se enquadra o estabelecimento;
• active – Valor booleano para indicar se o registro está ativo ou não (registros inativos não serão
  retornados nas buscas);
• address – Objeto com os detalhes do endereço:
  • street – String para informar o endereço;
  • number – String para o número do estabelecimento;
  • district – (Opcional) String para o bairro;
  • city – String para cidade;
  • state – String para estado;
  • zipcode – String para CEP;
  • point – Array com as coordenadas do estabelecimento:
    • latitude – Coordenada da latitude em graus decimais;
    • longitude – Coordenada da longitude em graus decimais;
• tags – (Opcional) Array de strings com “tags”, ou rótulos, para identificar o tipo de estabelecimento com categorias personalizadas;
• phones – (Opcional) Array de strings para os números de telefones de contato;
• additionalInfo – (Opcional) Objeto com informações adicionais sobre o ponto. As propriedades devem ser no formato string no padrão "key":"value"

Nota: Para consultar as categorias e subcategorias disponíveis para consulta e cadastro, basta fazer uma requisição para os seguintes endpoints (método GET) https://api.maplink.global/place/v1/places/category e https://api.maplink.global/place/v1/places/subcategory

Caso seja necessário atualizar algum registro existente, basta reenviar a requisição indicando o ID único com todos os parâmetros obrigatórios e os dados atualizados. 

O corpo da requisição deverá seguir a estrutura a seguir:

{
    "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",
        "Comida"
    ],
    "additionalInfo": {
        "Abre Final de Semana": "Sim",
        "Área para fumantes": "Sim"
    }
}

Como consultar um estabelecimento cadastrado

Para consultar todos os estabelecimentos cadastrados, basta realizar uma requisição do tipo GET para o seguinte endpoint, onde o termo {{placeId}} deve ser substituido pelo ID do estabelecimento desejado:

• https://api.maplink.global/place/v1/places/{{placeId}} – GET

Como consultar a base de estabelecimentos

Para consultar todos os estabelecimentos cadastrados, basta realizar uma requisição do tipo GET para o seguinte endpoint:

• https://api.maplink.global/place/v1/places – GET 

É possível filtrar os resultados da consulta via parâmetros na URL. Os seguintes filtros estão disponíveis:

• city – Filtrar resultados pela cidade;
• district – Filtrar resultados pelo bairro ou distrito;
• state – Filtrar resultados pelo estado;
• tag – Filtrar resultados pela tag;
• center – Coordenadas de referência para a busca de resultados. Formato: center=-23.552088765,-46.6341653162;
• radius – Especifica o raio de busca, em metros, a partir do ponto central definido em center.

Exemplo de utilização:
https://api.maplink.global/place/v1/places?city=Caieiras&state=SP&tags=abc123,restaurante&center=-23.364792,-46.783109&radius=149000&district=Centro

Também é possível paginar os resultados com os seguintes parâmetros:

• offset – Índice do primeiro valor;
• limit – Número de resultados por página, com limite de 100.

No exemplo abaixo, temos 20 estabelecimentos cadastrados e desejamos paginar os resultados, com cada página contendo 10 estabelecimentos. Para consultar a primeira página teríamos:
https://api.maplink.global/place/v1/places?offset=0&limit=10

Para a segunda página teríamos https://api.maplink.global/place/v1/places?offset=9&limit=10 e assim por diante.

Como consultar as categorias e subcategorias disponíveis

Para consultar a lista de todas as categorias disponíveis para o cadastro, basta realizar um requisição do tipo GET para o seguinte endpoint:

• https://api.maplink.global/place/v1/places/category –  GET 

Para consultar as subcategorias, utilizar o seguinte endpoint, também com o método GET:

• https://api.maplink.global/place/v1/places/subcategory –  GET

Como consultar estados, cidades e bairros dos estabelecimentos cadastrados

É possível consultar os estados, cidades ou bairros onde existem estabelecimentos cadastrados na base.

Consultar estados

Para consultar os estados onde existem estabelecimentos cadastrados, basta realizar uma requisição do tipo GET para o seguinte endpoint:

• https://api.maplink.global/place/v1/places/states –  GET 

O retorno virá no formato json, com um array contendo as siglas dos estados onde existem estabelecimentos cadastrados, conforme o exemplo abaixo:

[
    "RJ",
    "SP"
]

Consultar cidades

Para consultar as cidades onde existem estabelecimentos cadastrados, basta realizar uma requisição do tipo GET para o endpoint abaixo, onde o termo {{state}} deverá ser substituído pelo estado desejado:

• https://api.maplink.global/place/v1/places/state/{{state}}/cities –  GET 

O retorno virá no formato json, com um array contendo as cidades do estado solicitado onde existem estabelecimentos cadastrados, conforme o exemplo abaixo:

[
    "São Paulo",
    "Ribeirão Preto",
    "Campinas" 
]

Consultar bairros

Por fim, para consultar os bairros onde existem estabelecimentos cadastrados, basta realizar uma requisição do tipo GET para o endpoint abaixo, onde o termo {{state}} deverá ser substituído pelo estado desejado e o termo {{city}} pela cidade:

• https://api.maplink.global/place/v1/places/state/{{state}}/city/{{city}}/districts –  GET 

O retorno virá no formato json, com um array contendo os bairros da cidade e estado solicitados onde existem estabelecimentos cadastrados, conforme o exemplo abaixo:

[
    "Sé Bela Vista",
    "Bom Retiro",
    "Cambuci",
    "Aricanduva", 
]