City-level IP geolocation lookup with postal, subdivisions, and coordinates
openapi: 3.0.3
info:
title: MaxMind GeoIP Web Services GeoIP City API
description: 'MaxMind''s GeoIP web services provide IP geolocation data including country, city, ISP, organization, ASN, connection type, and VPN/proxy detection. Services are available at three tiers: Country, City Plus, and Insights. All endpoints use HTTP Basic Auth with your MaxMind account ID and license key.
'
version: '2.1'
contact:
name: MaxMind Support
url: https://support.maxmind.com/
termsOfService: https://www.maxmind.com/en/terms_of_service
license:
name: MaxMind End User License Agreement
url: https://www.maxmind.com/en/end_user_license_agreement
servers:
- url: https://geoip.maxmind.com
description: MaxMind GeoIP production server
- url: https://geolite.info
description: MaxMind GeoLite production server
security:
- basicAuth: []
tags:
- name: GeoIP City
description: City-level IP geolocation lookup with postal, subdivisions, and coordinates
paths:
/geoip/v2.1/city/{ipAddress}:
get:
operationId: getGeoIPCity
summary: GeoIP City Plus Lookup
description: 'Provides city-level geolocation data including city name, postal code, latitude and longitude with accuracy radius, metro code, time zone, and subdivisions. Also includes country, ISP, and organization data in a single response. Priced at $0.0003 per query.
'
tags:
- GeoIP City
parameters:
- $ref: '#/components/parameters/ipAddress'
responses:
'200':
description: Successful city lookup response
content:
application/json:
schema:
$ref: '#/components/schemas/CityResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
Forbidden:
description: 'The request is forbidden. Your account does not have access to this service, or the IP address is blocked.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: 'Too many requests have been sent in a given period. Slow down your request rate.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: 'No record found for the IP address. The IP address may be invalid or not in the database.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: 'The service requires payment. Check that your account has sufficient credits.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: 'There was an error authenticating the request. Verify your account ID and license key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: 'There was an error with the request. Check the code and error fields for details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: 'An unexpected error occurred on MaxMind''s servers.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
Country:
type: object
description: Country data for the IP address
properties:
confidence:
type: integer
description: Confidence percent (1-99) that the country is correct (Insights only)
minimum: 1
maximum: 99
example: 99
geoname_id:
type: integer
description: GeoNames ID for the country
example: 6252001
is_in_european_union:
type: boolean
description: Whether the country is a member of the EU
example: false
iso_code:
type: string
description: ISO 3166-1 alpha-2 country code
example: US
names:
$ref: '#/components/schemas/LocalizedNames'
RepresentedCountry:
type: object
description: Country that is represented by the IP address (e.g., military)
properties:
geoname_id:
type: integer
example: 6252001
is_in_european_union:
type: boolean
example: false
iso_code:
type: string
example: US
names:
$ref: '#/components/schemas/LocalizedNames'
type:
type: string
description: Type of represented country (e.g., "military", "satellite")
example: military
Continent:
type: object
description: Continent data for the IP address
properties:
code:
type: string
description: Two-letter continent code
example: NA
geoname_id:
type: integer
description: GeoNames ID for the continent
example: 6255149
names:
$ref: '#/components/schemas/LocalizedNames'
Postal:
type: object
description: Postal code data
properties:
code:
type: string
description: Postal code for the IP address
example: '55420'
confidence:
type: integer
description: Confidence percent (1-99) the postal code is correct
minimum: 1
maximum: 99
example: 60
Location:
type: object
description: Location data including coordinates and time zone
properties:
accuracy_radius:
type: integer
description: Estimated accuracy radius in kilometers
example: 20
latitude:
type: number
format: double
description: Approximate latitude
example: 44.9532
longitude:
type: number
format: double
description: Approximate longitude
example: -93.0875
metro_code:
type: integer
description: US metro code (US only)
example: 613
time_zone:
type: string
description: Time zone name as defined by the IANA Time Zone Database
example: America/Chicago
Subdivision:
type: object
description: Subdivision (state/province/region) data
properties:
confidence:
type: integer
description: Confidence percent (1-99) the subdivision is correct
minimum: 1
maximum: 99
example: 88
geoname_id:
type: integer
description: GeoNames ID for the subdivision
example: 5037779
iso_code:
type: string
description: ISO 3166-2 code for the subdivision
example: MN
names:
$ref: '#/components/schemas/LocalizedNames'
CityResponse:
type: object
description: Response from the GeoIP City Plus web service
properties:
city:
$ref: '#/components/schemas/City'
continent:
$ref: '#/components/schemas/Continent'
country:
$ref: '#/components/schemas/Country'
location:
$ref: '#/components/schemas/Location'
maxmind:
$ref: '#/components/schemas/MaxMindMeta'
postal:
$ref: '#/components/schemas/Postal'
registered_country:
$ref: '#/components/schemas/RegisteredCountry'
represented_country:
$ref: '#/components/schemas/RepresentedCountry'
subdivisions:
type: array
items:
$ref: '#/components/schemas/Subdivision'
traits:
$ref: '#/components/schemas/CityTraits'
LocalizedNames:
type: object
description: Localized names keyed by locale code (e.g., "en", "de", "fr")
additionalProperties:
type: string
example:
en: United States
de: Vereinigte Staaten
City:
type: object
description: City data for the IP address
properties:
confidence:
type: integer
description: Confidence percent (1-99) that the city is correct
minimum: 1
maximum: 99
example: 75
geoname_id:
type: integer
description: GeoNames ID for the city
example: 5037649
names:
$ref: '#/components/schemas/LocalizedNames'
ErrorResponse:
type: object
description: Standard error response
properties:
code:
type: string
description: Error code
example: IP_ADDRESS_INVALID
error:
type: string
description: Human-readable error description
example: The value 'foo' is not a valid IP address.
CityTraits:
allOf:
- $ref: '#/components/schemas/CountryTraits'
- type: object
properties:
autonomous_system_number:
type: integer
description: Autonomous System Number (ASN) for the IP address
example: 217
autonomous_system_organization:
type: string
description: Organization associated with the ASN
example: University of Minnesota
connection_type:
type: string
description: Connection type (Cable/DSL, Cellular, Corporate, Satellite)
example: Corporate
domain:
type: string
description: Second-level domain associated with the IP address
example: umn.edu
isp:
type: string
description: Name of the ISP
example: University of Minnesota
mobile_country_code:
type: string
description: Mobile Country Code (MCC) for mobile connections
example: '310'
mobile_network_code:
type: string
description: Mobile Network Code (MNC) for mobile connections
example: '004'
organization:
type: string
description: Name of the organization using the IP address
example: University of Minnesota
RegisteredCountry:
type: object
description: Country where the IP address is registered
properties:
geoname_id:
type: integer
example: 6252001
is_in_european_union:
type: boolean
example: false
iso_code:
type: string
example: US
names:
$ref: '#/components/schemas/LocalizedNames'
CountryTraits:
type: object
description: Traits associated with the IP address (Country tier)
properties:
ip_address:
type: string
description: The IP address that was looked up
example: 128.101.101.101
is_anycast:
type: boolean
description: Whether the IP is part of an anycast network
example: false
network:
type: string
description: CIDR network block associated with the record
example: 128.101.101.0/24
MaxMindMeta:
type: object
description: MaxMind account metadata
properties:
queries_remaining:
type: integer
description: Number of queries remaining in the current subscription period
example: 123456
parameters:
ipAddress:
name: ipAddress
in: path
required: true
description: 'The IP address you want to look up. Use "me" to look up the IP address of the current connection. Accepts IPv4 (dotted quad) or IPv6 (canonical form per RFC 5952).
'
schema:
type: string
example: 128.101.101.101
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Use your MaxMind account ID as the username and your license key as the password. All requests must be made over HTTPS.
'
externalDocs:
description: MaxMind GeoIP Web Services Documentation
url: https://dev.maxmind.com/geoip/docs/web-services/