GET /services/geolocations

Retrieves the MaxMind geoip data for the given IP address.

Retrieves the MaxMind geoip location data for the given IP address. A filter is required to identify which IP address to lookup. Only EQUALS or IN is supported. Samples:
  • ip_address = "127.0.0.1"
  • ip_address IN ( "127.0.0.1", "127.0.0.2" )
Table 1. GET /services/geolocations resource details
MIME Type

application/json

Table 2. GET /services/geolocations request parameter details
Parameter Type Optionality Data Type MIME Type Description

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

A filter is required to identify which IP address to lookup. Only EQUALS and IN are supported.

Examples: 
"ip_address" = "127.0.0.1"
"ip_address" IN ( "127.0.0.1", "127.0.0.2" )
Table 3. GET /services/geolocations response codes
HTTP Response Code Unique Code Description

200

The location data was retrieved.

404

1002

The IP address does not exist in the database.

422

1005

The provided IP address is invalid.

422

1010

A request parameter is not valid.

500

1020

An error occurred while looking up the geodata.

Response Description

The location data after it has been retrieved. A location object contains the following fields:
  • ip_address - String - The IP address to lookup.
  • city - City - Object containing details about the city that is associated with the IP address.
    • name - String - The name of the city.
    • geo_id - Integer - A unique identifier for the city as specified by GeoNames.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the city is correct.
  • continent - Continent - Object containing details about the continent that is associated with the IP address.
    • name - String - The name of the continent.
    • geo_id - Integer - A unique identifier for the continent as specified by GeoNames.
    • code - String - A two-character code for the continent associated with the IP address.
  • physical_country - Country - Object containing details about the country where MaxMind believes the end user is located.
    • name - String - The name of the country.
    • geo_id - Integer - A unique identifier for the country as specified by GeoNames.
    • iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
  • registered_country - Country - Object containing details about the country in which the ISP has registered the IP address.
    • name - String - The name of the country.
    • geo_id - Integer - A unique identifier for the country as specified by GeoNames.
    • iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
  • represented_country - Country - Object containing details about the country which is represented by users of the IP address. For instance, the country represented by an overseas military base.
    • name - String - The name of the country.
    • geo_id - Integer - A unique identifier for the country as specified by GeoNames.
    • iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
    • type - String - The type of represented country. Currently limited to military but may include other types in the future.
    Note: In QRadar® versions earlier than 7.5.0 UP4, the name field returns as "military." QRadar version 7.5.0 UP4 and later contain a fix that corrects this erroneous behavior.
  • location - Location - Object containing details about the city that is associated with the IP address.
    • accuracy_radius - Integer - The approximate accuracy radius in kilometers around the latitude and longitude for the IP address. This is the radius where MaxMind has a 67% confidence that the device using the IP address resides within the circle centered at the latitude and longitude with the provided radius.
    • average_income - Integer - The average income associated with the IP address.
    • latitude - Double - The approximate latitude of the location associated with the IP address. Latitude and Longitude are often near the center of population.
    • longitude - Double - The approximate longitude of the location associated with the IP address. Latitude and Longitude are often near the center of population.
    • metro_code - Integer - The metro code associated with the IP address. These are only available for IP addresses in the US. Returns the same metro codes as the Google AdWords API.
    • population_density - Integer - The estimated number of people per square kilometer.
    • timezone - String - The time zone associated with location, as specified by the IANA Time Zone Database. For example, “America/New_York”.
  • postal - Postal - Object containing details about the postal code that is associated with the IP address.
    • postal_code - String - The postal code associated with the IP address. These are available for some IP addresses in Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. Returns the first 3 characters for Canadian postal codes. Returns the the first 2-4 characters (outward code) for postal codes in the United Kingdom.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the postal code is correct.
  • subdivision - List of Subdivisions - Each of these objects contains details about a subdivision of the country in which the IP address resides. Subdivisions are arranged from largest to smallest.
    • name - String - The name of the subdivision.
    • geo_id - Integer - A unique identifier for the region as specified by GeoNames.
    • iso_code - String - A string of up to three characters that contains the region-portion of theISO 3166-2 code for the region associated with the IP address.
    • confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the region is correct.
  • traits - Traits - Object containing general traits that is associated with the IP address.
    • autonomous_system_number - Integer - The autonomous system number associated with the IP address.
    • autonomous_system_organization - String - The organization associated with the registered autonomous system number for the IP address.
    • domain - String - The second level domain associated with the IP address.
    • internet_service_provider - String - The name of the Internet Service Provider associated with the IP address.
    • organization - String - The name of the organization associated with the IP address.
    • user_type - String - The user type associated with the IP address.
  • geo_json - GeoJSON - A standardize GeoJSON point object for the IP address.
    • type - String - The type of GeoJSON. The default is "Point".
    • coordinates - Array of Double - Latitude and Longitude from the Maxmind Location object.
  • is_local - Boolean - True if the IP address is defined in the network hierarchy.
  • network - String - The local network that the IP address belongs to.
  • domain_id - Integer - The domain id of the local network.

Response Sample


[
    {
        "city": {
            "confidence": 42,
            "geo_id": 42,
            "name": "String"
        },
        "continent": {
            "code": "String",
            "geo_id": 42,
            "name": "String"
        },
        "domain_id": 42,
        "geo_json": {
            "coordinates": [
                42.5
            ],
            "type": "String"
        },
        "ip_address": "String",
        "is_local": true,
        "location": {
            "accuracy_radius": 42,
            "average_income": 42,
            "latitude": 42.5,
            "longitude": 42.5,
            "metro_code": 42,
            "population_density": 42,
            "timezone": "String"
        },
        "network": "String",
        "physical_country": {
            "confidence": 42,
            "geo_id": 42,
            "iso_code": "String",
            "name": "String"
        },
        "postal": {
            "confidence": 42,
            "postal_code": "String"
        },
        "registered_country": {
            "confidence": 42,
            "geo_id": 42,
            "iso_code": "String",
            "name": "String"
        },
        "represented_country": {
            "confidence": 42,
            "geo_id": 42,
            "iso_code": "String",
            "name": "String"
        },
        "subdivisions": [
            {
                "confidence": 42,
                "geo_id": 42,
                "iso_code": "String",
                "name": "String"
            }
        ],
        "traits": {
            "autonomous_system_number": 42,
            "autonomous_system_organization": "String",
            "domain": "String",
            "internet_service_provider": "String",
            "organization": "String",
            "user_type": "String"
        }
    }
]