Se você está nessa página, nós assumimos que:
Você já possui uma chave de acesso;

Tenha conhecimento sobre o funcionamento dos exemplos de código através do guia Primeiros passos;

Tenha conhecimento de XML e Web Services SOAP.

O serviço “Proximity” disponibiliza através de suas operações as funcionalidades de busca por pontos de interesse considerando como filtro por proximidade um endereço, coordenadas geográficas, dimensões de um mapa ou um valor de raio.

Os pontos de interesse são armazenados em uma base de dados criada e mantida pelo cliente. O acesso a esta estrutura é restrito ao seu dono, através da existência de uma validação pela chave de acesso (parâmetro “token”) informado como entrada para a requisição solicitada.

A estrutura abaixo contém as informações de versão, endereço de acesso e contrato de operação para o serviço Proximity.

Nome do serviço: Proximity
Endereço de acesso: http://services.maplink.com.br/webservices/v3/proximity/proximity.asmx
Versão atual: V3.0
Funcionalidade Nome da Operação
Pontos de interesse com proximidade por endereço FindClosestFromAddress
Pontos de interesse com proximidade por coordenadas geográficas FindClosestFromXY
Pontos de interesse com proximidade por dimensões de mapa FindFromExtent
Pontos de interesse com proximidade por endereço e raio FindRadiusFromAddress
Pontos de interesse com proximidade por coordenadas geográficas e raio FindRadiusFromXY

A funcionalidade de busca por pontos de interesse com proximidade por endereço está disponível através da operação “FindClosestFromAddress” e tem como objetivo retornar uma lista com os pontos de interesse encontrados a partir da base de dados informada (parâmetro “poiDataSource”), considerando uma cláusula de seleção (“whereClause”) caso exista, e os campos selecionados (“fieldList”) para a fonte de origem dos dados. Adicionalmente, a entrada da operação recebe como parâmetro os dados de um endereço.

A resposta desta operação possui o nome da tabela usada para obter os pontos de interesse, coordenadas geográficas para o endereço informado, distância em metros do ponto de interesse até o endereço informado e uma lista com campos customizados solicitados na requisição da busca.

Contrato de entrada – Requisição

O contrato de requisição possui os parâmetros “ad” (Address), “po” (ProximityOptions) e “token”, sendo estes descritos em detalhe a seguir:

  • ad

Armazena uma implementação da estrutura Address com os dados de endereço.

  • po

Armazena uma implementação da estrutura ProximityOptions com os dados de opções de busca para os pontos de interesse.

  • token

Armazena a chave de acesso do requisitante.

Estrutura “Address” contém as informações de nome e número da rua, código postal, bairro, cidade e estado.
Nome do Atributo Tipo Descrição
street Conjunto de caracteres Indica o nome da rua
houseNumber Conjunto de caracteres Indica o número da rua
zip Conjunto de caracteres Indica o código postal
district Conjunto de caracteres Indica o nome da bairro
city Estrutura City Indica a cidade e estado
Estrutura “City” contém as informações do nome da cidade e de seu estado.
Nome do Atributo Tipo Descrição
name Conjunto de caracteres Indica o nome da cidade
state Conjunto de caracteres Indica o nome do estado
Estrutura “ProximityOptions” contém dados de filtro para a busca por pontos de interesse com proximidade, armazenando a fonte de origem dos dados, campos customizados para retorno da busca, filtro de seleção e sistema de paginação através da estrutura “ResultRange”
Nome do Atributo Tipo Descrição
poiDataSource Conjunto de caracteres Indica da fonte de origem dos pontos de interesse
fieldList Conjunto de caracteres Indica o nome dos campos a serem retornadas na busca. Permite a inclusão de mais de um campo, sendo necessário separá-los pelo caracter “|”, por exemplo: “campo1|campo2″
whereClause Conjunto de caracteres Indica a cláusula de filtro para a seleção dos dados. Segue estrutura de condição de um banco de dados relacional, por exemplo: “campo1 LIKE ‘panificadora%’”
resultRange Estrutura ResultRange Indica os parâmetros do sistema de paginação usado nos resultados
Estrutura “ResultRange” contém os atributos para definir a paginação para a busca realizada.
Nome do Atributo Tipo Descrição
pageIndex Número inteiro Indica o índice da página de retorno
recordsPerPage Número inteiro Indica o número de registros por página

Contrato de saída – Resposta

O contrato de resposta possui os parâmetros “pageCount”, “recordCount” e “resultSet” (ProximityResult), sendo estes descritos em detalhe a seguir:

  • pageCount

Armazena um número inteiro com a página corrente para o sistema de paginação.

  • recordCount

Armazena um número inteiro com a quantidade de registros existentes para a página corrente.
Atualmente a aplicação possui um limite de 50 registros por página, mesmo caso o valor fornecido para este campo seja superior ao estipulado.

  • resultSet

Armazena um conjunto de implementações da estrutura “ProximityResult” com os dados de retorno.

Estrutura “ProximityResult” contém os dados de retorno de uma requisição de busca de pontos de interesse por proximidade e possui a composição de uma matriz, sendo necessário acessar os valores por posição, por exemplo: proximityResult[0]
Nome do Atributo Tipo Descrição
Posição 0 – proximityResult[0] Conjunto de caracteres Indica o nome da fonte de origem (tabela)
Posição 1 – proximityResult[1] Conjunto de caracteres Indica a longitude correspondente a um endereço
Posição 2 – proximityResult[2] Conjunto de caracteres Indica a latitude correspondente a um endereço
Posição 3 – proximityResult[3] Conjunto de caracteres Indica a distância em metros entre o endereço informado e o ponto de interesse corrente
Posição 4 em diante Conjunto de caracteres Indica o valor presente no campo customizável indicado através do parâmetro “fieldList” da estrutura ProximityOptions. Caso seja selecionado um segundo campo customizável ele será representado na posição 5, e assim sucessivamente para os demais campos.

Consumo

A seguir é apresentando um exemplo de consumo do serviço “Proximity” utilizando a operação “FindClosestFromAddress”, com o objetivo de obter dados de pontos de interesse existentes em uma determinada base de dados. Como as fontes de dados pertencem a clientes, os dados expostos representaram um cenário simulado de requisição e resposta.

Como parâmetros de entrada são fornecidos os dados para a estrutura “City” com rua “Avenida Paulista”, número “1000″, cidade “São Paulo” e estado “SP”, além dos parâmetros para a estrutura “ProximityOptions” com poiDataSource “VTB_CUSTOMER”, fieldList “field1|field2″, whereClausule “field2 LIKE ‘supermarket%’” e sistema de paginação através da estrutura “ResultRange” com os valores “1″ e “3″, para os parâmetros “pageIndex” e “recordsPerPage”, respectivamente.

Abaixo são apresentandos exemplos de implementação para consumo da operação em diferentes linguagens de programação.

O serviço recebe a requisição, realiza o processamento interno e retorna uma mensagem no formato XML com o resultado da operação.

XML SOAP de resposta:


A funcionalidade de busca por pontos de interesse com proximidade por endereço está disponível através da operação “FindClosestFromAddress” e tem como objetivo retornar uma lista com os pontos de interesse encontrados a partir da base de dados informada (parâmetro “poiDataSource”), considerando uma cláusula de seleção (“whereClause”) caso exista e os campos selecionados (“fieldList”) para a fonte de origem dos dados. Adicionalmente, a entrada da operação recebe como parâmetro os dados de um endereço.

Esta funcionalidade possui a mesma estrutura de entrada e saída da operação FindClosestFromAddress, tendo como única diferença o fato de informar o endereço desejado para comparar a distância em metros para cada ponto de interesse encontrado como coordenadas geográficas, informando as posições X e Y, longitude e latitude respectivamente.

A resposta desta operação possui o nome da tabela usada para obter os pontos de interesse, coordenadas geográficas para o endereço informado, distância em metros do ponto de interesse até o endereço informado (em coordenadas geográficas) e uma lista com os campos customizados requeridos na solicitação da busca.

Contrato de entrada – Requisição

O contrato de requisição possui os parâmetros “point” (Point), “po” (ProximityOptions) e “token”, sendo estes descritos em detalhe a seguir:

  • point

Armazena uma implementação da estrutura Point com os dados das coordenadas geográficas.

  • po

Armazena uma implementação da estrutura ProximityOptions com os dados de opções de busca para os pontos de interesse.

  • token

Armazena a chave de acesso do requisitante.

Estrutura “Point” contém as coordenadas de latitude e longitude para um determinado endereço
Nome do Atributo Tipo Descrição
X Número com casas decimais Indica a longitude de uma coordenada geográfica
Y Número com casas decimais Indica a latitude de uma coordenada geográfica

Contrato de saída – Resposta

O contrato de resposta possui os parâmetros “pageCount”, “recordCount” e “resultSet” (ProximityResult), sendo estes descritos em detalhe a seguir:

  • pageCount

Armazena um número inteiro com a página corrente para o sistema de paginação.

  • recordCount

Armazena um número inteiro com a quantidade de registros existentes para a página corrente.

  • resultSet

Armazena um conjunto de implementações da estrutura “ProximityResult” com os dados de retorno.

Consumo

A seguir é apresentando um exemplo de consumo do serviço “Proximity” utilizando a operação “FindClosestFromXY”, com o objetivo de obter dados de pontos de interesse existentes em uma determinada base de dados. Como as fontes de dados pertencem a clientes, os dados expostos representaram um cenário simulado de requisição e resposta.

Como parâmetros de entrada são fornecidos os dados para a estrutura “Point” com longitude “-46.6520066″ e latitude “-23.5650127″, além dos parâmetros para a estrutura “ProximityOptions” com poiDataSource “VTB_CUSTOMER”, fieldList “field1|field2″, whereClausule “field2 LIKE ‘supermarket%’” e sistema de paginação através da estrutura “ResultRange” com os valores “1″ e “3″, para os parâmetros “pageIndex” e “recordsPerPage”, respectivamente.

Abaixo são apresentandos exemplos de implementação para consumo da operação em diferentes linguagens de programação.

O serviço recebe a requisição, realiza o processamento interno e retorna uma mensagem no formato XML com o resultado da operação.

XML SOAP de resposta:


A funcionalidade de busca por pontos de interesse com proximidade por dimensões de mapa está disponível através da operação “FindFromExtent” e tem como objetivo retornar uma lista com os pontos de interesse encontrados a partir da base de dados informada (parâmetro “poiDataSource”), considerando uma cláusula de seleção (“whereClause”) caso exista e os campos selecionados (“fieldList”) para a fonte de origem dos dados. Adicionalmente, a entrada da operação recebe como parâmetro os dados de dimensões de um mapa. Somente são retornados os pontos de interesse que estejam dentro da área informado através da estrutura Extent.

Esta funcionalidade possui a mesma estrutura de entrada e saída da operação FindClosestFromAddress, tendo como única diferença o fato de informar o endereço desejado para comparar a distância em metros para cada ponto de interesse encontrado como dimensões de um mapa, através de uma área de cobertura.

A resposta desta operação possui o nome da tabela usada para obter os pontos de interesse, coordenadas geográficas para o endereço informado, distância em metros do ponto de interesse até o endereço informado (área de uma região em uma mapa) e uma lista com os campos customizados requeridos na solicitação da busca.

Contrato de entrada – Requisição

O contrato de requisição possui os parâmetros “ext” (Extent), “po” (ProximityOptions) e “token”, sendo estes descritos em detalhe a seguir:

  • ad

Armazena uma implementação da estrutura Extent com as dimensões de uma área no mapa através dos valores mínimos e máximos para as coordenadas X e Y.

  • po

Armazena uma implementação da estrutura ProximityOptions com os dados de opções de busca para os pontos de interesse.

  • token

Armazena a chave de acesso do requisitante.

Estrutura “Extent” representa a área do mapa através dos valores mínimos e máximos para as coordenadas X e Y
Nome do Atributo Tipo Descrição
XMin Número com casas decimais Indica o valor mínimo da coordenada X
XMax Número com casas decimais Indica o valor máximo da coordenada Y
YMin Número com casas decimais Indica o valor mínimo da coordenada X
YMax Número com casas decimais Indica o valor máximo da coordenada Y
Contrato de saída – Resposta

O contrato de resposta possui os parâmetros “pageCount”, “recordCount” e “resultSet” (ProximityResult), sendo estes descritos em detalhe a seguir:

  • pageCount

Armazena um número inteiro com a página corrente para o sistema de paginação.

  • recordCount

Armazena um número inteiro com a quantidade de registros existentes para a página corrente.

  • resultSet

Armazena um conjunto de implementações da estrutura “ProximityResult” com os dados de retorno.

Consumo

A seguir é apresentando um exemplo de consumo do serviço “Proximity” utilizando a operação “FindFromExtent”, com o objetivo de obter dados de pontos de interesse existentes em uma determinada base de dados. Como as fontes de dados pertencem a clientes, os dados expostos representaram um cenário simulado de requisição e resposta.

Como parâmetros de entrada são fornecidos os dados para a estrutura “Extent” com valores “-46.65218″, “-23.56501″, “-46.61399″, “-23.52279″, para os parâmetros “XMin”, “YMin”, “XMax”, “YMax” respectivamente, além dos parâmetros para a estrutura “ProximityOptions” com poiDataSource “VTB_CUSTOMER”, fieldList “field1|field2″, whereClausule “field2 LIKE ‘supermarket%’” e sistema de paginação através da estrutura “ResultRange” com os valores “1″ e “3″, para os parâmetros “pageIndex” e “recordsPerPage”, respectivamente.

Abaixo são apresentandos exemplos de implementação para consumo da operação em diferentes linguagens de programação.

O serviço recebe a requisição, realiza o processamento interno e retorna uma mensagem no formato XML com o resultado da operação.

XML SOAP de resposta:


A funcionalidade de busca por pontos de interesse com proximidade por endereço e raio está disponível através da operação “FindRadiusFromAddress” e tem como objetivo retornar uma lista com os pontos de interesse encontrados a partir da base de dados informada (parâmetro “poiDataSource”), considerando uma cláusula de seleção (“whereClause”) caso exista e os campos selecionados (“fieldList”) para a fonte de origem dos dados. Adicionalmente, a entrada da operação recebe como parâmetro os dados de um endereço e um valor raio. Somente são retornados os pontos de interesse que estejam dentro do raio estipulado a partir do endereço informado.

A resposta desta operação possui o nome da tabela usada para obter os pontos de interesse, coordenadas geográficas para o endereço informado, distância em metros do ponto de interesse até o endereço informado e uma lista com os campos customizados requeridos na solicitação da busca.

Contrato de entrada – Requisição

O contrato de requisição possui os parâmetros “ad” (Address), “po” (ProximityOptions) e “token”, sendo estes descritos em detalhe a seguir:

  • ad

Armazena uma implementação da estrutura Address com os dados de endereço.

  • po

Armazena uma implementação da estrutura ProximityOptions com os dados de opções de busca para os pontos de interesse.

  • token

Armazena a chave de acesso do requisitante.

Contrato de saída – Resposta

O contrato de resposta possui os parâmetros “pageCount”, “recordCount” e “resultSet” (ProximityResult), sendo estes descritos em detalhe a seguir:

  • pageCount

Armazena um número inteiro com a página corrente para o sistema de paginação.

  • recordCount

Armazena um número inteiro com a quantidade de registros existentes para a página corrente.

  • resultSet

Armazena um conjunto de implementações da estrutura “ProximityResult” com os dados de retorno.

Consumo

A seguir é apresentando um exemplo de consumo do serviço “Proximity” utilizando a operação “FindClosestFromAddress”, com o objetivo de obter dados de pontos de interesse existentes em uma determinada base de dados. Como as fontes de dados pertencem a clientes, os dados expostos representaram um cenário simulado de requisição e resposta.

Como parâmetros de entrada são fornecidos os dados para a estrutura “City” com rua “Avenida Paulista”, número “1000″, cidade “São Paulo” e estado “SP”, raio com valor “100″, além dos parâmetros para a estrutura “ProximityOptions” com poiDataSource “VTB_CUSTOMER”, fieldList “field1|field2″, whereClausule “field2 LIKE ‘supermarket%’” e sistema de paginação através da estrutura “ResultRange” com os valores “1″ e “3″, para os parâmetros “pageIndex” e “recordsPerPage”, respectivamente.

Abaixo são apresentandos exemplos de implementação para consumo da operação em diferentes linguagens de programação.

O serviço recebe a requisição, realiza o processamento interno e retorna uma mensagem no formato XML com o resultado da operação.

XML SOAP de resposta:


A funcionalidade de busca por pontos de interesse com proximidade por coordenadas geográficas e raio está disponível através da operação “FindRadiusFromXy” e tem como objetivo retornar uma lista com os pontos de interesse encontrados a partir da base de dados informada (parâmetro “poiDataSource”), considerando uma cláusula de seleção (“whereClause”) caso exista e os campos selecionados (“fieldList”) para a fonte de origem dos dados. Adicionalmente, a entrada da operação recebe como parâmetro os dados de um endereço e um valor raio. Somente são retornados os pontos de interesse que estejam dentro do raio estipulado a partir do endereço (em coordenadas geográficas) informado.

Esta funcionalidade possui a mesma estrutura de entrada e saída da operação FindRadiusFromAddress, tendo como única diferença o fato de informar o endereço desejado para considerar os pontos de interesse a serem localizados como coordenadas geográficas, informando as posições X e Y, longitude e latitude respectivamente.

A resposta desta operação possui o nome da tabela usada para obter os pontos de interesse, coordenadas geográficas para o endereço informado, distância em metros do ponto de interesse até o endereço informado e uma lista com os campos customizados requeridos na solicitação da busca.

Contrato de entrada – Requisição

O contrato de requisição possui os parâmetros “point” (Point), “po” (ProximityOptions) e “token”, sendo estes descritos em detalhe a seguir:

  • point

Armazena uma implementação da estrutura Point com os dados das coordenadas geográficas.

  • po

Armazena uma implementação da estrutura ProximityOptions com os dados de opções de busca para os pontos de interesse.

  • token

Armazena a chave de acesso do requisitante.

Contrato de saída – Resposta

O contrato de resposta possui os parâmetros “pageCount”, “recordCount” e “resultSet” (ProximityResult), sendo estes descritos em detalhe a seguir:

  • pageCount

Armazena um número inteiro com a página corrente para o sistema de paginação.

  • recordCount

Armazena um número inteiro com a quantidade de registros existentes para a página corrente.

  • resultSet

Armazena um conjunto de implementações da estrutura “ProximityResult” com os dados de retorno.

Consumo

A seguir é apresentando um exemplo de consumo do serviço “Proximity” utilizando a operação “FindClosestFromAddress”, com o objetivo de obter dados de pontos de interesse existentes em uma determinada base de dados. Como as fontes de dados pertencem a clientes, os dados expostos representaram um cenário simulado de requisição e resposta.

Como parâmetros de entrada são fornecidos os dados para a estrutura “Point” com longitude “-46.6520066″ e latitude “-23.5650127″ e raio com valor “100″, além dos parâmetros para a estrutura “ProximityOptions” com poiDataSource “VTB_CUSTOMER”, fieldList “field1|field2″, whereClausule “field2 LIKE ‘supermarket%’” e sistema de paginação através da estrutura “ResultRange” com os valores “1″ e “3″, para os parâmetros “pageIndex” e “recordsPerPage”, respectivamente.

Abaixo são apresentandos exemplos de implementação para consumo da operação em diferentes linguagens de programação.

O serviço recebe a requisição, realiza o processamento interno e retorna uma mensagem no formato XML com o resultado da operação.

XML SOAP de resposta: