canonical: https://jentic.com/apis/maxmind.com/maxmind # MaxMind GeoIP Web Services API MaxMind's GeoIP and GeoLite web services return IP geolocation intelligence for any IPv4 or IPv6 address, including country, city, postal code, ASN, ISP, and risk insights. The API has three endpoints - country, city, and insights - each accepting a specific IP or the requesting client's IP via the 'me' alias. It powers fraud screening, content localisation, and traffic analytics workloads where a server-side lookup is needed before serving a response. ## For AI agents Look up the country, city, ASN, ISP, and risk score for any IP address. Use to localise responses, screen suspicious traffic, or enrich session logs. ## Scope Does not handle device fingerprinting, email validation, or phone-number lookup - use for IP-based geolocation and risk enrichment only. ## Capabilities - Resolve country, continent, and registered country for an IPv4 or IPv6 address - Return city-level data including postal code, latitude, longitude, and time zone - Surface insights data such as user type, autonomous system number, and ISP - Look up the requesting client's own IP via the 'me' alias without passing it explicitly - Distinguish anonymous proxies, hosting providers, and residential connections for risk scoring - Switch between the paid GeoIP service and the free GeoLite tier using the same request shape ## Use cases ### Fraud Screening on Sign-Up Score new account sign-ups by enriching the request IP with MaxMind insights data before the account is provisioned. The /insights/{ipAddress} endpoint returns user type (residential, hosting, anonymous proxy), ISP, and connection type, which feeds a rules engine to flag high-risk registrations. Combined with email and device signals, this is a standard layer of defence against bot and synthetic-identity fraud. Example prompt: Call GET /insights/198.51.100.42, parse the user_type and traits.is_anonymous fields, and return 'high_risk' if user_type is 'hosting' or is_anonymous is true. ### Content Localisation Serve currency, language, and pricing variants tailored to the visitor's country without requiring an explicit selection. The /country/{ipAddress} endpoint returns ISO country codes that drive localisation rules, with /me as the address parameter when the lookup is for the current client. Latency is low enough to run in line with the initial page render. Example prompt: Call GET /country/me, read the country.iso_code field, and choose between USD, EUR, and GBP pricing based on the result. ### Session and Log Enrichment Enrich web server logs and analytics events with city-level geographic data so analysts can break down traffic by region without storing raw IPs in their warehouse. The /city/{ipAddress} endpoint returns city, subdivisions, postal code, and approximate coordinates, which can be appended to events at ingest time. This satisfies regional reporting needs while keeping the underlying IP out of downstream BI tools. Example prompt: For each IP in a batch of 100 log lines, call GET /city/{ip} and append city.names.en, postal.code, and country.iso_code to the corresponding event. ### AI Agent for Suspicious Login Triage Build an agent that, when alerted to a suspicious login, fetches MaxMind insights for the source IP, compares it to the user's historical countries and ISPs, and posts a triage summary back to the security channel. The agent searches Jentic for 'IP risk lookup', loads the insights schema, and executes the call with the IP in question. The result is a faster human-in-the-loop decision on whether to force a password reset. Example prompt: For IP 203.0.113.7 from a login by user_id 42, call GET /insights/203.0.113.7, then return a one-paragraph summary noting country, ISP, anonymous-proxy flag, and whether the country differs from the user's last 90-day login history. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /country/{ipAddress} | Look up country and continent for an IP | | GET | /city/{ipAddress} | Look up city, postal code, and coordinates | | GET | /insights/{ipAddress} | Look up ISP, ASN, user type, and risk traits | ## Key resources - **Country** — Country and continent lookup for an IP address - **City** — City, postal code, coordinates, and subdivisions for an IP - **Insights** — ISP, ASN, user type, and risk traits for an IP ## Why Jentic - **Setup:** Wiring the MaxMind GeoIP Web Services API by hand means combining your account ID and license key into a Basic auth header, choosing the geoip or geolite host, and mapping the lookup calls yourself. Through Jentic you install once, import the MaxMind GeoIP Web Services API from the API Directory, store the account ID and license key once, and your agent calls it. - **Permission scoping:** The IP address MaxMind resolves is supplied per request rather than being a stored resource you own, so you limit the agent to the operations it needs, such as a country, city, or insights lookup. It calls only the operations you allow, and since this surface is read-only, it enriches data without any write access. - **Credential handling:** Your MaxMind account ID and license key are stored once, encrypted, by your own Jentic One instance and combined into a Basic auth header at execution time. The license key never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'look up the risk score for an IP address', and Jentic returns the matching MaxMind operation, country, city, or insights, with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **ipstack** — IP geolocation API with a free tier and similar country/city/insights split - **ipapi** — Lightweight IP geolocation with REST and JSONP support - **Abstract IP Geolocation** — IP geolocation as one of a suite of data-validation APIs ## FAQ ### What authentication does the MaxMind GeoIP API use? HTTP Basic authentication with the MaxMind account ID as the username and the license key as the password. Through Jentic, the credentials are stored in your Jentic One instance and attached to outbound requests at execution time, so the license key never enters the agent's context. ### Can I detect anonymous proxies with the MaxMind API? Yes, via the /insights/{ipAddress} endpoint. The response includes traits.is_anonymous, traits.is_anonymous_proxy, traits.is_hosting_provider, and traits.user_type, which together let you flag VPNs, Tor exits, and datacentre IPs that often correlate with fraudulent traffic. ### What are the rate limits for the MaxMind GeoIP API? MaxMind enforces request limits based on your subscription quota rather than a per-second cap; you draw down a pool of queries purchased in advance. Responses include headers indicating remaining queries on your account. The free GeoLite tier on geolite.info is more strictly throttled and intended for low-volume use. ### How do I look up an IP's country with the MaxMind API through Jentic? Search Jentic for 'look up country for IP', load the schema for GET /country/{ipAddress}, and execute with the IP in the path parameter. To resolve the requesting client's IP, pass 'me' as the path value. Jentic attaches the Basic auth header automatically. ### What is the difference between GeoIP and GeoLite? Both use the same v2.1 endpoint shape but are served from different hosts: geoip.maxmind.com is the paid, higher-accuracy service; geolite.info hosts the free, less precise GeoLite2 data. The agent points at the correct base URL depending on which subscription is in use. ### Can the MaxMind API return latitude and longitude? Yes, via the /city/{ipAddress} and /insights/{ipAddress} endpoints. The location object includes latitude, longitude, and accuracy_radius (in km). Coordinates are estimates derived from the IP block, not the device GPS, so accuracy is city-level at best. ### Can I limit what my agent is allowed to do with the MaxMind GeoIP Web Services API? Yes. Because you run Jentic One yourself, your own rules decide which MaxMind operations your agent may call and which credentials it may use, so you can allow only a country lookup while blocking the more detailed city or insights operations. The IP address is passed per request rather than being a stored resource you own, so the agent can only read data for the specific address it queries. Since all three endpoints, GET /country, GET /city, and GET /insights, are read-only, the agent enriches your data without any write access to your MaxMind account.