Guia do desenvolvedor do GlideGeoPoint

O guia do desenvolvedor GlideGeoPoint contém informações sobre como calcular distâncias entre valores de latitude e longitude (geopoints), retornar locais dentro de determinados valores de ponto geográfico e raio e usar a funcionalidade adicional fornecida por funções de API GlideGeoPoint compatíveis.

O Geo point field type permite armazenar um par de latitude e longitude em um único campo. Os pontos geográficos podem ser úteis sempre que você quiser armazenar um ponto geográfico de interesse, para perguntar a que distância dois pontos de interesse estão um do outro ou para pesquisar todos os pontos dentro de uma certa distância de outro ponto. Por exemplo, você pode usar a funcionalidade de geoponto para determinar rapidamente todos os locais de entrega do cliente e ajustar as taxas de entrega com base na distância da loja.

Os principais aspectos do tipo de dados de geotipo são:

• Ele consiste em um par de números decimais que representam valores de longitude e latitude.
• O intervalo de longitude é (-180, 180). Qualquer valor fora deste intervalo é normalizado para o valor equivalente dentro deste intervalo.
• O intervalo de latitude é [-90, 90]. Qualquer valor fora deste intervalo é normalizado para o valor equivalente dentro deste intervalo.
• Os valores de ponto geográfico são sempre aceitos como entrada e são exibidos como um par separado por vírgulas: "longitude,latitude". Opcionalmente, os parênteses podem cercar a expressão.
• Os valores de longitude e latitude são armazenados com até 6 casas decimais de precisão.

Para obter mais informações sobre o tipo de dados de ponto geográfico, consulte Function field.

Os exemplos neste guia presumem que uma tabela personalizada, u_geopoint, é preenchida com campos u_name e u_location, em que u_name é do tipo "cadeia de caracteres" e lista os nomes das principais cidades e u_location é do tipo "geopoint" e lista a latitude/longitude pontos de cada cidade, respectivamente.

Criar geopoints usando a API GlideGeoPoint

Use a API GlideGeoPoint para inserir novos registros e criar novos geopoints.

A API GlideGeoPoint - Global permite que você defina e recupere valores de geopoint. No entanto, você pode executar uma funcionalidade adicional para inserir novos registros definindo geopoints diretamente em um script usando notação de cadeia de caracteres ou um objeto GlideGeoPoint.

Inserindo um novo registro usando notação de cadeia de caracteres.

Defina o valor do campo de ponto geográfico u_location usando uma cadeia de caracteres. A cadeia de caracteres consiste em um par delimitado por vírgulas de valores de longitude e latitude. O exemplo a seguir mostra como definir um novo geopoint na tabela u_geopoint usando a notação de cadeia de caracteres.

Nota:

Os valores da APIGlideGeoPoint são sempre listados na ordem de longitude e latitude.

const longitude = "-87.628018"; 
const latitude = "41.885778"; 
const geopoint = longitude + "," + latitude; 
 
const myGeoPoint = new GlideRecord("u_geopoint"); 
myGeoPoint.initialize(); 
myGeoPoint.setValue("u_name", "Chicago"); 
myGeoPoint.setValue("u_location", geopoint); 
myGeoPoint.insert();

Inserção de um novo registro usando o objeto GlideGeoPoint.

Defina o valor do campo de geopoint u_location usando um objeto GlideGeoPoint.

const longitude = -87.628018; 
const latitude = 41.885778; 
const geopoint = new GlideGeoPoint(longitude, latitude); 
 
const myGeoPoint = new GlideRecord("u_geopoint"); 
myGeoPoint.initialize(); 
myGeoPoint.setValue("u_name", "Chicago"); 
myGeoPoint.setValue("u_location", geopoint); 
myGeoPoint.insert();

Ler valores de geopoint usando a API GlideGeoPoint

Use a função de API getDisplayValue() GlideGeoPoint para ler todos os valores de geopoint de uma tabela específica.

A API GlideGeoPoint padrão permite que você recupere um valor de ponto geográfico por meio da função GlideGeoPoint – getDisplayValue(). No entanto, é possível ler todos os geopoints definidos em uma tabela inteira. O script de exemplo a seguir demonstra como usar a função getDisplayValue() para recuperar todos os registros da tabela u_geopoint, que inclui o campo u_location do tipo 'geopoint'. Você pode usar este script de exemplo e ajustá-lo ao seu caso de uso específico.

Nota:

Os valores da APIGlideGeoPoint são sempre listados na ordem de longitude e latitude.

const myGeoPoint = new GlideRecord("u_geopoint"); 
myGeoPoint.query(); 
 
while (gr.next()) 
  gs.info("Name: {0}  Location: {1}",  
    myGeoPoint.getDisplayValue('u_name'),  
    myGeoPoint.getDisplayValue('u_location'));

A saída retorna todos os registros na tabela u_geopoint. O valor de exibição de um geopoint inclui a longitude seguida pela latitude, separada por uma vírgula e entre parênteses.

Name: London  Location: (-0.189937, 51.473584) 
Name: Puerto Rico  Location: (-66.561301, 18.291136) 
Name: Glasgow  Location: (-4.223964, 55.867846) 
Name: Chicago  Location: (-87.628018, 41.885778) 
Name: Tasmania  Location: (146.757677, -42.173578) 
Name: Bermuda  Location: (-64.761595, 32.315798) 
Name: Miami  Location: (-80.206458, 25.767242) 
Name: Sydney  Location: (151.205230, -33.890115) 
Name: Perth  Location: (115.871253, -31.971583) 
Name: Dublin  Location: (-6.304994, 53.348317)

Calcular a distância entre dois pontos geográficos

Use a função de glide field_sphere para retornar a distância entre geopoints em metros.

A função de geopoint glide, field_sphere, permite calcular a distância entre dois geopoints. A função retorna a distância em metros. O field_sphere pode ser usado na definição de um elemento de campo de função em uma tabela ou por meio de um script. Três sintaxes são compatíveis e todos os parâmetros são necessários:

• glidefunction:istance_sphere(geopoint1, geopoint2)
• glidefunction:istance_sphere(geopoint1, longitude2, latitude2)
• glidefunction:istance_sphere(longitude1, latitude1, longitude2, latitude2)

Ao usar essas sintaxes, observe que:

• geopoint1 e geopoint2 são elementos de tabela do tipo 'geopoint'
• longitude1, longitude 2, latitude 1, latitude 2 são elementos de tabela numérica ou constantes
• Em todos os casos, o valor de retorno desta função é um decimal que representa a distância entre dois pontos geográficos em metros

O script de exemplo a seguir define uma função de domain_sphere para calcular a distância entre todos os geopoints armazenados no campo u_location da tabela u_geopoint e o ponto -0.189937 longitude, 51.473584 latitude (que é aproximadamente a localização de Londres). A função é adicionada à consulta GlideRecord para produzir resultados.

const distToLondon =  
"glidefunction:distance_sphere(u_location, '-0.189937', '51.473584')"; 
 
const myGeoPoint = new GlideRecord('u_geopoint'); 
gr.addFunction(distToLondon); 
gr.query(); 
 
while(myGeoPoint.next()) 
  gs.info("Name: {0}  Dist to London(m): {1}",  
    myGeoPoint.u_name, gr.getValue(distToLondon));

A saída lista a distância entre Londres e as cidades no campo u_location em metros.

Name: London  Dist to London(m): 0 
Name: Glasgow  Dist to London(m): 555985.58456358 
Name: Dublin  Dist to London(m): 464000.328892816 
Name: Miami  Dist to London(m): 7123803.25406323 
Name: Bermuda  Dist to London(m): 5547607.95564083 
Name: Puerto Rico  Dist to London(m): 6799201.00905107 
Name: Perth  Dist to London(m): 14485217.5596414 
Name: Sydney  Dist to London(m): 17001034.4875494 
Name: Tasmania  Dist to London(m): 17324634.4559516 

Filtrar a distância entre dois pontos geográficos

Use a condição de consulta DISTANCE_SPHERE_WITHIN para filtrar registros que tenham um valor de ponto geográfico dentro do raio de um ponto de latitude e longitude definido.

DISTANCE_SPHERE_WITHIN deve seguir a sintaxe geopointDISTANCE_SPHERE_WITHINlongitude,latitude <radius em que:

• geopoint é um campo de geopoint
• longitude e latitude são constantes decimais​s
• raio é uma constante decimal (em metros)

Nota:

O símbolo de menor que (<) nesta expressão é necessário e usado somente como um delimitador. Qualquer outro operador de comparação é inválido.

O DISTANCE_SPHERE_WITHIN aceita valores de quilômetro ou medidor na solicitação, mas sempre retorna o valor de saída em metros.

O script de exemplo a seguir mostra como criar uma consulta codificada que retorna somente registros com um u_location a menos de 1.000.000 quilômetros de distância do ponto -0,189937 longitude, 51,473584 latitude (que é aproximadamente a localização de London). Quando executado, ele retorna três registros que representam cidades dentro do raio especificado de Londres.

const myGeoPoint = new GlideRecord("u_geopoint");  
myGeoPoint.addEncodedQuery("u_locationDISTANCE_SPHERE_WITHIN-0.189937,51.473584<1000000");  
myGeoPoint.query(); 
 
while(gr.next()) 
    gs.info("Name:" + myGeoPoint.getDisplayValue("u_name")   
         + " Location:" + myGeoPoint.getDisplayValue("u_location"));

Saída:

Name:London Location:(-0.189937, 51.473584) 
Name:Dublin Location:(-6.304994, 53.348317) 
Name:Glasgow Location:(-4.223964, 55.867846)

O script de exemplo a seguir é equivalente ao primeiro, mas usa uma sintaxe alternativa para GlideRecord.

const myGeoPoint = new GlideRecord("u_geopoint");  
myGeoPoint.addQuery("u_location", "DISTANCE_SPHERE_WITHIN", "-0.189937,51.473584<1000000");  
myGeoPoint.query(); 
 
while(myGeoPoint.next()) 
    gs.info("Name:" + myGeoPoint.getDisplayValue("u_name")   
         + " Location:" + myGeoPoint.getDisplayValue("u_location"));

Saída:

Name:London Location:(-0.189937, 51.473584) 
Name:Dublin Location:(-6.304994, 53.348317) 
Name:Glasgow Location:(-4.223964, 55.867846)