Introduction

Our API is an alternative way to access our conversion services directly through HTTP requests. Its recommended to use the SDK unless your environment cannot install JavaScript packages.

We have simplified the API to make it easy to use with clear endpoints and consistent request/response structures.

Authentication

All API requests require the x-api-key header. You can use either key type:

• Secret key (i2g_sk_…), for server-side requests. Generated from the Secret Keys section in your dashboard. It works on every route, reading your conversions included, so keep it on your server.

• Public key (i2g_pk_…), for client-side (browser) conversions. Generated from the Websites section. The request’s Origin header must match the registered domain, which browsers send on their own, but any other client can send any Origin. So a public key only converts addresses, which count toward your quota, and gets 403 on the /conversions routes.

# Server-side with secret key
curl --request GET \
    --url https://api.ip2geo.dev/convert?ip=8.8.8.8 \
    --header 'x-api-key: i2g_sk_your_secret_key'

# Client-side with public key (browser sends Origin automatically)
fetch('https://api.ip2geo.dev/convert?ip=8.8.8.8', {
    headers: { 'x-api-key': 'i2g_pk_your_public_key' }
})

OpenAPI

The whole API is described in an OpenAPI 3.0 document at https://ip2geo.dev/openapi.json. Import it into Postman or Insomnia, or generate a client from it. The reference pages in this section are built from the same document.

Responses and Limits

• Every answer, error or not, is the same JSON envelope: success, code (the HTTP status), message, data and _req, whose reqId identifies the request when you contact us.

• Every address you send counts toward your plan’s quota, valid or not. An invalid address answers 400, and a valid one with no geolocation record (private, reserved and unassigned addresses have none) answers 404; both still count. In a bulk conversion they come back with conversion: null.

• Conversions are kept for the current month and the twelve before it. Asking for an older one by id answers 404, and POST /conversions/get leaves ids it cannot find out of its answer instead of failing.

• While the API is under maintenance every route answers 503 in the same envelope. https://api.ip2geo.dev/maintenance/status says when it is over.

When to Use the API Instead of the SDK?

• Environment Limitations: If your environment can’t install JavaScript packages (e.g., a non-JavaScript runtime).

• Direct Control: If you need direct control over HTTP requests for specific use cases that the SDK doesn’t cover.

• Lightweight Needs: If you want to avoid adding an additional dependency to your project.