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;

$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

$response = Http::withToken('REPLACE_WITH_API_TOKEN')
    ->acceptJson()
    ->post('https://api.provero.io/api/fraud-check/geoip', [
        'ip' => $ip,
        'address' => $address,
        'geoMatch' => $geoMatch,
    ]);

return $response->json();

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.