Implementar endpoint de frequência média de pessoas por hora em uma área visível do mapa (zoom / viewport)

[manoelcampos]

Método HTTP	URI	Descrição
GET	/localizacao/frequencia-pessoas/{area}	Frequência (média) de pessoas que visitam um local por hora em uma determinada área visível do mapa (viewport). O retorno pode ser um objeto contendo todas essas estatísticas.

O sistema não saberá qual o nome do local selecionado pelo usuário, mas o usuário como usará o mapa para encontrar o lugar desejado (clicando ou digitando o nome do lugar), ele sabe a que local se refere.
Ele pode controlar o zoom para definir a área visível do mapa. A partir daí podemos obter o viewport, que é um retângulo para a área visivel. Desta forma, conseguimos filtrar os pontos que estejam dentro deste retângulo e computar estatísticas.

O viewport representa dois pontos de um retângulo: o ponto superior esquerdo e o ponto inferior direito. Com estes pontos podemos facilmente filtrar os dados no select que estejam dentro de tal área. Para as cada estatística será uma consulta diferente, agrupando os dados por hora, dia, semana ou mês.

No app/frontend usuário terá então algumas possibilidades (isto deve ser outra issue):

• clicar em um ponto qualquer
• usar um campo de busca para encontrar o local desejado (a Places API inclusive fornece recursos de autocomplete para tal campo)
• detectar a alteração no viewport e quando o usário parar de alterar o zoom, enviar requisição.

No app/frontend, tais informações podem aparecer no Marker onde o usuário clicou/selecionou (que será implementado em issue específica).

Detalhes de implementação

Cada endereço tem um ID único no Google Maps chamado Place ID.
Este ID pode ser salvo no banco para uso posterior, sem infringir as políticas de uso do serviço.

Como o servidor irá receber um único ponto, ele fará uma única requisição à API de reverse geocoding para obter o Place ID.
Mas como a Places API aparentemente só aceita o nome do endereço, deve ser usada a API de reverse geocoding do Maps para, a partir de um ponto, descobrir qual o endereço/nome do local.

Um exemplo de uso da Places API está disponível aqui (lá tem outro link para o código fonte do exemplo, abaixo do mapa).

Depois de termos o Place ID, podemos obter os detalhes do local.
A resposta será um objeto PlaceResult. Na requisição devemos indicar quais detalhes queremos obter.
Um dos detalhes indicados no link acima é o atributo geometry.
Tal atributo é um objeto contendo o campo viewport que representa um retângulo delimitando a área visiível no mapa. No link anterior, tem outro link para a documentação deste atributo que mostra isso.

Se o viewport for muito grande, é preciso pedir que o usuário selecione uma área mais específica aumentando o zoom.

AVISO

Observar que o atributo geometry de viewport é opcional, então teremos problema se ele não existir.

Issues Relacionadas

• Implementar endpoints REST para estatísticas por área (viewport) #142
• Habilitar swagger para specificação de endpoints REST #10
• Implementar endpoints REST para inserir e obter localizacao #14