IP geolocation API

Get the approximate location of the current request without asking for device location.

This is the network the request arrived on. It is not a GPS fix, and it is not a lookup of an address you supply. Maps, geocoding, and routing stay the primary APIs. IP geolocation is a small primitive on the same key.

IP geolocation is approximate. Results may identify the city or region associated with the user's network rather than the user's physical location. VPNs, mobile networks, corporate networks, and proxies can substantially change the result.

Every request needs an API key; see Authentication. One request is one call on the same pool as maps, geocoding, and routing. There is no separate credit.

IP geolocation can answer for a request outside Canada, wherever the network metadata exists. That does not extend maps, geocoding, or routing. Routing coverage remains Canada.

The gateway does not store the result, and it does not add a location field to its request log. The log stays what it already is: method, endpoint class, status, and timing.

import { Unmap } from "@unmap/sdk";
 
const unmap = new Unmap({ key: "um_live_..." });
const location = await unmap.geolocation.ip();
 
console.log(location.city);
console.log(location.country);

@unmap/sdk exposes this as unmap.geolocation.ip(). There is no separate package, and no React or Vue hook: the call is one await.

GET /ip

No parameters besides the key. The location is the caller's. You cannot pass an address.

curl "https://api.unmap.dev/ip?key=YOUR_KEY"

import { Unmap } from "@unmap/sdk";
 
const unmap = new Unmap({ key: "um_live_..." });
const location = await unmap.geolocation.ip();

The key also works as Authorization: Bearer or X-API-Key, same as every other route.

{
  "ip": "203.0.113.42",
  "location": { "lat": 51.05, "lng": -114.07 },
  "city": "Calgary",
  "region": "Alberta",
  "regionCode": "AB",
  "postalCode": "T2P",
  "country": "CA",
  "continent": "NA",
  "timezone": "America/Edmonton",
  "network": { "asn": 12345, "organization": "Example ISP" },
  "precision": "approximate"
}

A field the network did not identify is null. The request still returns 200.

{
  "city": null,
  "postalCode": null,
  "country": "CA",
  "precision": "approximate"
}

precision is always "approximate". Coordinates are rounded to two decimal places, about a kilometre. country is ISO 3166-1 alpha-2.

Cache-Control is private, no-store. Do not put this response in a shared cache. It describes the caller, and the next caller is somebody else.

import { Unmap } from "@unmap/sdk";
 
const key = "um_live_...";
const unmap = new Unmap({ key });
const geo = await unmap.geolocation.ip();
 
const map = new Unmap({
  key,
  container: "#map",
  center:
    geo.location.lng != null && geo.location.lat != null
      ? [geo.location.lng, geo.location.lat]
      : [-96, 56],
});

center is [longitude, latitude]. The fallback is a view of Canada for when the network named neither coordinate. The pin is a starting viewport, not a claim about where the person is.

What this does not do

• Look up an arbitrary IP. GET /ip/{address} is not part of this API.
• Keep a history of addresses, or build a profile of a visitor.
• Detect VPNs, proxies, or Tor, or score a request for fraud.
• Ask the browser for device location.

A server error is reserved for the gateway actually failing. Missing metadata is a partial body, not an error.