canonical: https://jentic.com/apis/hirak.site/hirak-ip-to-country

# Hirak Site Hirak IP to Country API

The Hirak IP to Country API resolves an IPv4 or IPv6 address to a country, exposed through two GET endpoints - one returning the country for the caller's own IP and one accepting an explicit IP path parameter. The service is unauthenticated and intentionally narrow, which makes it suitable for low-cost geolocation gating, basic analytics, and language-defaulting in apps that do not need city-level resolution. Latency is generally low because the response payload is small and the surface is read-only.

## For AI agents

Resolve an IP address (the caller's or an explicit one) to a country code with two GET endpoints. No authentication required.

## Scope

Does not return city, region, ISP, latitude, or longitude - use for IP-to-country lookups only.

## Capabilities

- Detect the country for the caller's IP address with GET /
- Resolve a specific IPv4 or IPv6 address to a country via GET /{ip}
- Default site language or currency based on visitor country
- Block or allow access by country to enforce regional gating
- Tag analytics events with a country code for geographic reporting

## Use cases

### Visitor Locale Defaulting

Public websites set the default language and currency from the visitor's country. The Hirak IP to Country API's GET / returns the country for the caller's IP, which is enough to choose between English-US and English-GB or to default a price to EUR. Because the endpoint is unauthenticated, integration is just a fetch call.

Example prompt: On the first page render, call GET / to get the visitor's country and set the locale to fr-FR if the country is FR or en-GB if the country is GB.

### Geographic Access Gating

Some products are unavailable in specific regions. An agent can call GET /{ip} for an inbound request and reject the call before any business logic runs if the country is on the blocklist. This is faster and cheaper than a full IP-intelligence service for simple country-level rules.

Example prompt: For an inbound API call with source IP 203.0.113.12, call GET /203.0.113.12 and return 451 if the country code is in the blocklist.

### Lightweight Analytics Enrichment

Analytics pipelines tag events with a country code for geographic dashboards. Hirak's per-IP endpoint returns the country quickly enough to enrich event records in a streaming job without the overhead of a self-hosted MaxMind database or a paid geolocation vendor.

Example prompt: For each event in a streaming pipeline, call GET /{ip} with the source IP and write the country code into the enriched record.

### AI Agent Geo-Aware Reply

An AI assistant tailors replies based on the user's region. Through Jentic, the agent searches for the IP-to-country operation, loads the schema, and executes GET / against the user's request IP. No credentials are needed, but Jentic standardises the call surface so the agent treats it like any other tool.

Example prompt: When the user asks 'what's the weather like here', search Jentic for 'get country from IP', execute GET /, and use the country code to choose a weather data source.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/` | Get the country for the caller's IP |
| GET | `/{ip}` | Get the country for a specific IP |

## Key resources

- **Caller IP Lookup** — Returns the country for the caller's source IP.
- **Explicit IP Lookup** — Returns the country for any IPv4 or IPv6 address supplied as a path parameter.

## Why Jentic

- **Setup:** Wiring the Hirak IP to Country API by hand still means routing each lookup to the correct endpoint, choosing between the caller-IP default and an explicit /{ip} path, even though the service needs no credentials. Through Jentic you install once, import the Hirak IP to Country API from the API Directory, and your agent calls it through the same execution path as keyed APIs.
- **Permission scoping:** The Hirak IP to Country API is an unauthenticated read-only lookup with the IP as a path value rather than a scopable account resource, so scoping stays at the operation level: limit the agent to the operations it needs, either the caller-IP lookup or the explicit /{ip} lookup. You choose that set, so it does only the country lookups you allow.
- **Credential handling:** The Hirak IP to Country API is unauthenticated, so there is no credential to store, and Jentic still runs each call through the same execution path as keyed APIs. No secret ever enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get country from IP', and Jentic returns the GET / or GET /{ip} operation with its parameter schema so the agent picks the right one without reading the reference docs.

## Related APIs

- **IPGeolocation API** — Geolocation API with city, region, ISP, and timezone data beyond country resolution.
- **ipstack API** — Commercial IP geolocation with currency, language, and security signals.
- **MaxMind GeoIP API** — Industry-standard IP intelligence with offline database and risk scoring.
- **Abstract IP Geolocation API** — IP geolocation as part of Abstract's wider utility-API bundle.

## FAQ

### What authentication does the Hirak IP to Country API use?

The Hirak IP to Country API does not require authentication - both GET / and GET /{ip} are public. Through Jentic the API is wired into the same execution flow as authenticated APIs, so the agent's call pattern is consistent across tools.

### Can I look up a specific IP address?

Yes. GET /{ip} accepts an IPv4 or IPv6 address as a path parameter and returns the country for that address. Use GET / when you want the country for the caller's own IP without supplying the value.

### What level of geographic detail does the API return?

Country only. The API does not return city, region, latitude, or longitude. If you need finer resolution, pair it with a city-level geolocation API such as ipgeolocation.io or MaxMind.

### What are the rate limits for the Hirak IP to Country API?

The OpenAPI specification does not declare rate limits. Treat the service as best-effort and add retry-with-backoff when enriching high-volume event streams to avoid being throttled at the network edge.

### How do I gate access by country through Jentic?

Run pip install jentic, then await client.search('get country from IP'), load the GET /{ip} schema, and execute it with the request source IP. Compare the returned country code against your blocklist before proceeding with business logic.

### Is the response shape stable enough for production use?

The response is a simple JSON object containing the country code; it has the smallest possible surface so changes are unlikely. Pin the field name in your code and validate the response before relying on the country value.

### Can I limit what my agent is allowed to do with the Hirak IP to Country API?

Yes. Because you run Jentic One yourself, your own rules decide which of this API's operations the agent may call, so you can scope it at the operation level. The Hirak IP to Country API is an unauthenticated read-only lookup, so scoping is about which of its two operations you allow: the caller-IP lookup at GET / and the explicit-address lookup at GET /{ip}. Grant the agent only the operation it needs, and it can perform just the country lookups you permit and nothing more.