MaxMind GeoIP Insights API

openapi: 3.0.3
info:
  title: MaxMind GeoIP Web Services GeoIP City GeoIP Insights 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 Insights
  description: 'Most comprehensive IP data lookup including anonymizer/VPN/proxy detection, user type, static IP score, and connection details

    '
paths:
  /geoip/v2.1/insights/{ipAddress}:
    get:
      operationId: getGeoIPInsights
      summary: GeoIP Insights Lookup
      description: 'MaxMind''s most comprehensive IP data API, returning all GeoIP City Plus fields plus additional intelligence including connection type, ISP, organization, user type, domain, anonymous IP and proxy/VPN/Tor detection flags. Priced at $0.002 per query.

        '
      tags:
      - GeoIP Insights
      parameters:
      - $ref: '#/components/parameters/ipAddress'
      responses:
        '200':
          description: Successful insights lookup response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResponse'
        '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'
    InsightsLocation:
      allOf:
      - $ref: '#/components/schemas/Location'
      - type: object
        properties:
          average_income:
            type: integer
            description: Average income in US dollars for the area (US only)
            example: 52000
          population_density:
            type: integer
            description: Population density per square kilometer for the area
            example: 1100
    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'
    InsightsTraits:
      allOf:
      - $ref: '#/components/schemas/CityTraits'
      - type: object
        properties:
          ip_risk_snapshot:
            type: number
            format: double
            description: IP risk score snapshot from 0.01 to 99
            example: 0.5
          static_ip_score:
            type: number
            format: double
            description: Score indicating how static the IP is (0-99.99)
            example: 1.5
          user_count:
            type: integer
            description: Estimated number of users sharing the IP in the past 24 hours
            example: 1
          user_type:
            type: string
            description: 'Type of user associated with the IP address. Possible values: business, cafe, cellular, college, consumer_privacy_network, content_delivery_network, dialup, government, hosting, library, military, residential, router, school, search_engine_spider, traveler

              '
            example: business
    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.
    Anonymizer:
      type: object
      description: Anonymizer and proxy detection data (Insights only)
      properties:
        confidence:
          type: integer
          description: Confidence in the anonymizer detection (0-99)
          minimum: 0
          maximum: 99
          example: 85
        is_anonymous:
          type: boolean
          description: Whether the IP belongs to an anonymous network
          example: false
        is_anonymous_vpn:
          type: boolean
          description: Whether the IP is associated with an anonymous VPN service
          example: false
        is_hosting_provider:
          type: boolean
          description: Whether the IP belongs to a hosting provider
          example: false
        is_public_proxy:
          type: boolean
          description: Whether the IP is a public proxy
          example: false
        is_residential_proxy:
          type: boolean
          description: Whether the IP is part of a residential proxy network
          example: false
        is_tor_exit_node:
          type: boolean
          description: Whether the IP is a Tor exit node
          example: false
        network_last_seen:
          type: string
          description: Date the network was last seen as an anonymizer (ISO 8601)
          example: '2024-01-15'
        provider_name:
          type: string
          description: Name of the VPN or proxy provider if known
          example: NordVPN
    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
    InsightsResponse:
      type: object
      description: Response from the GeoIP Insights web service
      properties:
        anonymizer:
          $ref: '#/components/schemas/Anonymizer'
        city:
          $ref: '#/components/schemas/City'
        continent:
          $ref: '#/components/schemas/Continent'
        country:
          $ref: '#/components/schemas/Country'
        location:
          $ref: '#/components/schemas/InsightsLocation'
        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/InsightsTraits'
    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/