Verifique se um endereço está no raio de entrega
Decida em uma etapa se um endereço está na sua área de entrega: um endereço a 6,283267 km em linha reta do centro fica dentro de um raio de 10 km. Informe os dois pares de coordenadas e o raio. Grátis no seu navegador.
- Grátis
- Funciona no seu navegador
- Sem cadastro
- Seus dados não saem do seu aparelho
Executar grátis
Exemplo resolvido
- Latitude do centro
- 40,7128
- Longitude do centro
- -74,006
- Latitude do endereço
- 40,73061
- Longitude do endereço
- -73,935242
- Raio máximo (km)
- 10
- Distância (km)
- 6,283267
Uma promessa de entrega costuma começar com uma pergunta prática: este endereço está perto o bastante do centro designado? Informe latitude e longitude do centro, latitude e longitude do endereço e o raio máximo em quilômetros. A capacidade valida os dois pares, calcula a distância de grande círculo em linha reta e retorna uma decisão clara junto da distância medida. O cálculo é determinístico, dispensa mapas e atende verificações no checkout, filtros de despacho e regras operacionais reproduzíveis.
Como a decisão da área de entrega é calculada
A capacidade considera o centro como o ponto central de uma área circular e o raio máximo informado como seu limite. Ela calcula a menor distância sobre a superfície entre o centro e o endereço pela fórmula de Haversine, com raio médio fixo da Terra de 6371.0088 quilômetros. O resultado é a distância de grande círculo, também chamada distância em linha reta.
A comparação usa o valor interno completo. O modelo não analisa ruas, pontes, rios, trânsito, restrições nem polígonos desenhados. Use-o quando a regra comercial for radial ou como filtro econômico antes de um sistema de rotas ou territórios mais caro.
Preparação das coordenadas e leitura dos erros
Latitudes usam graus decimais de -90 a 90 e longitudes de -180 a 180, com os extremos incluídos. O raio deve ser zero ou positivo; zero aceita apenas o mesmo ponto do centro. Um erro comum é trocar latitude por longitude.
Como muitas longitudes cabem na faixa de latitude, o pedido pode passar e apontar para outro lugar. Mantenha a mesma ordem na geocodificação, no armazenamento e na solicitação. Use posições geográficas em graus decimais, não metros projetados, CEPs ou endereços brutos.
Geocodifique antes e preserve precisão adequada. A validação não confirma se um ponto válido corresponde ao prédio, acesso ou marcador pretendido.
Uso seguro no checkout e no despacho
Com vários centros, avalie cada um, descarte resultados false e ordene os demais por distância, estoque, carga ou prazo. Estar no raio não garante rota viável nem entrega bem-sucedida. Litoral, vias restritas, pedágios, balsas, condomínios e territórios locais podem inviabilizar um ponto próximo.
Nesses casos, complemente o filtro radial com rotas ou polígonos. Defina o raio por uma política comercial explícita. O cálculo não usa rede, aleatoriedade nem horário atual; entradas iguais geram respostas iguais.
Corrija falhas de validação na origem, sobretudo campos invertidos e geocodificação incompleta.
Casos de uso
Elegibilidade de entrega no checkout
Decida se um endereço geocodificado fica perto o bastante de um centro antes de oferecer entrega local ou no mesmo dia.
Seleção do centro elegível mais próximo
Compare o endereço com vários centros, remova os que excedem o raio e classifique os restantes por estoque e carga.
Controle de qualidade do despacho
Valide coordenadas armazenadas e registre distância e resultado reproduzíveis para análise operacional e exceções.
Perguntas frequentes
A distância acompanha as ruas?
Não. É a distância de grande círculo sobre a superfície da Terra. Rotas, trânsito e restrições exigem um serviço de roteamento.
Posso enviar o endereço em vez das coordenadas?
Não. Geocodifique o endereço e envie latitude e longitude decimais junto às coordenadas do centro.
Quanto custa uma verificação?
O cálculo é determinístico e não consulta provedores de mapas.
Um endereço exatamente no limite do raio conta como dentro?
Sim. O endereço está na área quando a distância é menor ou igual ao raio, e a comparação usa a distância completa, sem arredondamento, então o arredondamento exibido na tela nunca muda a decisão.
O que acontece se eu inverter latitude e longitude?
Muitos pares invertidos continuam parecendo válidos, porque a maioria das longitudes também cabe na faixa de latitudes, mas descrevem outro lugar. Mantenha sempre a mesma ordem, da geocodificação até esta verificação.
Ferramentas relacionadas
Para desenvolvedores — acesso via API
Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.
Endpoint
Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.
Chame do seu código
curl -X POST https://api.kit.forhosting.com/ecom/last-mile-delivery-zone-check \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"hub_lat":40.7128,"hub_lon":-74.006,"address_lat":40.73061,"address_lon":-73.935242,"max_radius_km":10}'const res = await fetch("https://api.kit.forhosting.com/ecom/last-mile-delivery-zone-check", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"hub_lat": 40.7128,
"hub_lon": -74.006,
"address_lat": 40.73061,
"address_lon": -73.935242,
"max_radius_km": 10
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/ecom/last-mile-delivery-zone-check",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"hub_lat": 40.7128,
"hub_lon": -74.006,
"address_lat": 40.73061,
"address_lon": -73.935242,
"max_radius_km": 10
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/ecom/last-mile-delivery-zone-check", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"hub_lat":40.7128,"hub_lon":-74.006,"address_lat":40.73061,"address_lon":-73.935242,"max_radius_km":10}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"hub_lat":40.7128,"hub_lon":-74.006,"address_lat":40.73061,"address_lon":-73.935242,"max_radius_km":10}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/ecom/last-mile-delivery-zone-check", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Exemplo de requisição
{
"hub_lat": 40.7128,
"hub_lon": -74.006,
"address_lat": 40.73061,
"address_lon": -73.935242,
"max_radius_km": 10
}Exemplo de resposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "ecom.last_mile_delivery_zone_check",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.
Preço
Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.
Erros
| HTTP | Código | O que significa |
|---|---|---|
401 | unauthorized | Token ausente ou inválido. Confira o header Authorization. |
402 | insufficient_balance | Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo. |
404 | unknown_type | Esse tipo de tarefa não existe. Confira o campo type no catálogo. |
429 | rate_limited | Muitas requisições em pouco tempo. Espere um instante e tente de novo. |
Notas técnicas
Como a decisão da área de entrega é calculada
Se o valor integral, antes do arredondamento, for menor ou igual ao raio máximo, within_zone será true; caso contrário, false. A resposta inclui distance_km com seis casas decimais e repete max_radius_km para manter registros e decisões compreensíveis.
Preparação das coordenadas e leitura dos erros
Forneça cinco números finitos: hub_lat, hub_lon, address_lat, address_lon e max_radius_km. Valores ausentes, texto não numérico, infinitos ou coordenadas fora da faixa retornam invalid_input.
Uso seguro no checkout e no despacho
No checkout, execute a capacidade depois de converter o endereço em coordenadas e use within_zone como uma entrada da oferta. Guarde distance_km na auditoria do pedido para que o atendimento possa explicar a opção exibida. Cada item de API bem-sucedido custa US$ 0,002.
Perguntas técnicas
Um endereço exatamente no limite está incluído?
Sim. within_zone será true quando a distância integral for menor ou igual a max_radius_km.
O que ocorre se um par de coordenadas for inválido?
Latitude ou longitude ausente, não finita ou fora da faixa retorna invalid_input, sem distância nem decisão.