IP Geolocation API - FreeAPIService docs

Base path: /ip

Resolves an IPv4 address to its geographic location using the bundled IP2LOCATION-LITE-DB5 dataset. The lookup is backed by the geo_ip table.

Blockchain Caffe FreeAPIService uses the IP2Location LITE database for IP geolocation.

GET /ip/geo

Returns the geolocation associated with the requested IPv4 address.

Query parameters

Parameter	Required	Description
`ip`	yes	IPv4 address to look up, e.g. `8.8.8.8`.

Responses

Status	Body
`200`	Geolocation object (see below)
`400`	`{ "error": "ip is mandatory" }` when `ip` is missing or empty
`400`	`{ "error": "not a valid ipv4 address" }` when `ip` is not a valid IPv4 address
`404`	`{ "error": "no record found" }` when no address range matches

Response fields

Field	Type	Description
`country_code`	string	ISO 3166-1 alpha-2 country code; `-` when unknown
`country_name`	string	Country name
`region_name`	string	Region or state name
`city_name`	string	City name
`latitude`	number	Latitude in decimal degrees
`longitude`	number	Longitude in decimal degrees
`map_url`	string	OpenStreetMap link centred on the coordinates, with a marker

The ip_from and ip_to range columns are internal and are removed from the response.

Examples

Look up 8.8.8.8:

curl "$BASE_URL/ip/geo?ip=8.8.8.8"

{
    "city_name": "Mountain View",
    "country_code": "US",
    "country_name": "United States of America",
    "latitude": 37.38605,
    "longitude": -122.08385,
    "map_url": "https://www.openstreetmap.org/?mlat=37.38605&mlon=-122.08385#map=15/37.38605/-122.08385",
    "region_name": "California"
}

Missing IP address:

curl -i "$BASE_URL/ip/geo"

HTTP/1.1 400 Bad Request
{
    "error": "ip is mandatory"
}

Invalid IPv4 address:

curl -i "$BASE_URL/ip/geo?ip=not-an-ip"

HTTP/1.1 400 Bad Request
{
    "error": "not a valid ipv4 address"
}

Data source

The geo_ip table is imported from database/IP2LOCATION-LITE-DB5.CSV. To rebuild it:

./scripts/update_geoip.sh "$(pwd)/api.db" "$(pwd)/database/IP2LOCATION-LITE-DB5.CSV"

The script drops and recreates the table before importing, so any previous contents are replaced. Only IPv4 addresses are supported.