Provero Logo

IP Geolocation

The IP Geolocation API provides insights about the country and city associated with an IP address, along with optional distance comparison to a user-provided address.
This can be used to flag unexpected or foreign leads without affecting lead acceptance decisions.

Endpoint

POST 
https://api.provero.io/api/fraud-check/geoip

Headers

Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json

Request Body

Field Type Required Description
ip string Yes The IP address to be validated.
address string No Optional address or postcode to calculate distance from IP location. Required if geoMatch is used.
geoMatch boolean No Enable matching between IP’s geolocation and the supplied address.
Request Body example (JSON)
{
    "ip": "8.8.8.8",
    "address": "London",
    "geoMatch": true
}

Code Examples

import requests

ip = "0.0.0.0" # Replace with clients IP
address = "REPLACE_WITH_AN_ADDRESS" # Optional address for distance calculation
geoMatch = true # Enable geoMatch to compare IP location with address

url = "https://api.provero.io/api/fraud-check/geoip"
headers = {
    "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {"ip": ip, "address": address, "geoMatch": geoMatch}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)
<?php
$ip = "0.0.0.0"; // Replace with clients IP
$address = "REPLACE_WITH_AN_ADDRESS"; // Optional address for distance calculation
$geoMatch = true; // Enable geoMatch to compare IP location with address

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/fraud-check/geoip",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "ip" => $ip,
        "address" => $address,
        "geoMatch" => $geoMatch
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type: application/json",
        "Accept: application/json"
    ]
]);

$response = curl_exec($curl);
if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;
const ip = "0.0.0.0"; // Replace with clients IP
const address = "REPLACE_WITH_AN_ADDRESS"; // Optional address for distance calculation
const geoMatch = true; // Enable geoMatch to compare IP location with address

fetch("https://api.provero.io/api/fraud-check/geoip", {
    method: "POST",
    headers: {
        "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    body: JSON.stringify({ ip, address, geoMatch })
})
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.error("Error:", error));
ip="0.0.0.0" # Replace with clients IP
address="REPLACE_WITH_AN_ADDRESS" # Optional address for distance calculation
geoMatch=true # Enable geoMatch to compare IP location with address

curl -X POST https://api.provero.io/api/fraud-check/geoip \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{ \"ip\": \"$ip\", \"address\": \"$address\", \"geoMatch\": $geoMatch }"

Response Examples

Success 
{
    "country": "Ireland",
    "regionName": "Leinster",
    "city": "Dublin",
    "zip": "D02",
    "lat": "53.3498",
    "lon": "-6.26031",
    "ip": "46.51.128.144",
    "distance": {
        "km": 0.0514,
        "mi": 0.0319
    },
    "geoMatch": {
        "country": true,
        "city": true
    }
}
Application Error 
{
    "requestError": {
        "serviceException": {
            "messageId": "Error message",
            "code": "400"
        }
    }
}
Payment Required - Insufficient Balance 
{
    "message": "Insufficient balance for validation request.",
    "service": "geoip",
    "required_amount": "0.0060000000",
    "current_balance": "0.0000000000"
}
Validation Error - IP Not Provided 
{
    "message": "The ip field is required.",
    "errors": {
        "ip": [
            "The ip field is required."
        ]
    }
}
Validation Error - Invalid IP Address 
{
    "message": "The ip field must be a valid IP address.",
    "errors": {
        "ip": [
            "The ip field must be a valid IP address."
        ]
    }
}
Validation Error - Geomatch - Destination Not Valid 
{
    "message": "Please provide a valid destination to match.",
    "errors": {
        "address": [
            "Please provide a valid destination to match."
        ]
    }
}

Response Body

Success structure

Field Name Type Example Always Present Description
country string Ireland Yes Country of the IP's location
regionName string Leinster Yes Region/province/state
city string Dublin Yes City of the IP location
zip string D02 Yes Postcode of the IP
lat string 53.3498 Yes Latitude
lon string -6.2603 Yes Longitude
ip string 46.51.128.144 Yes IP address submitted
distance.km string 0.051 No Distance to address (km)
distance.mi string 0.031 No Distance to address (miles)
geoMatch.country boolean true No Country match result
geoMatch.city boolean true No City match result

Error structure

Field Name Type Example Always Present Description
message string The ip field is required. No Top-level error message returned on validation failure, insufficient balance, or other request errors.
errors object {"ip": ["The ip field is required."]} No Object of validation services with validation failures.
requestError object {"serviceException": {"messageId": "Error message", "code": "400"}} No Object containing service exceptions for application errors.
service string geoip No Service alias returned with a 402 insufficient-balance response.
required_amount string 0.0060000000 No Credit amount required to process the validation request.
current_balance string 0.0000000000 No Current available balance at the time the request was rejected.