Guia do desenvolvedor de 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 geopoint e raio e usar a funcionalidade adicional fornecida pelas 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 estão dois pontos de interesse ou para pesquisar todos os pontos dentro de uma certa distância de outro ponto. Por exemplo, você pode usar a funcionalidade de ponto geográfico 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 geoponto são sempre aceitos como entrada e exibidos como um par separado por vírgulas: "longitude,latitude". Os parênteses podem opcionalmente envolver 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 os 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 geopontos usando a API GlideGeoPoint

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

A API GlideGeoPoint - Global permite definir e recuperar valores de geopoint. No entanto, você pode executar funcionalidades adicionais para inserir novos registros definindo geopoints diretamente em um script usando notação de cadeia de caracteres ou um objeto GlideGeoPoint.

Inserção de 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 notação de cadeia de caracteres.

Nota:

Os valores da APIGlideGeoPoint são sempre listados em 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 geopoint por meio da função GlideGeoPoint – getDisplayValue(). No entanto, é possível ler todos os geopontos 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 próprio caso de uso específico.

Nota:

Os valores da APIGlideGeoPoint são sempre listados em 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 ponto geográfico 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 geopontos

Use a função glide distância_espira para retornar a distância entre os pontos geográficos em metros.

A função de glide de geopoint, location_sphere , permite que você calcule a distância entre dois geopoints. A função retorna a distância em metros. O location_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éricos 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 distância 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
• raio é uma constante decimal (em metros)

Nota:

O símbolo de menor que (<) nesta expressão é obrigatório e usado somente como 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 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)