IP to Location database MMDB format

The format used in the IP to Location MMDB database files is compliant with version 2.0 of the specification and is compatible with free MMDB reader libraries.

Schema

In order to maximize compatibility with existing tools and libraries, we try to stay as close as possible to their expected schema.

city.geoname_id uint32: Unique ID of the city in the Geonames open database
city.names map<utf8_string>: City name in all available languages
continent.code utf8_string: Two-letter continent code [AF, AS, EU, NA, OC, SA, AN]
continent.geoname_id uint32: Unique ID of the continent in the Geonames open database
continent.names map<utf8_string>: Continent name in all available languages
country.geoname_id uint32: Unique ID of the country in the Geonames open database
country.iso_code utf8_string: ISO 3166-1 alpha-2 country code
country.is_in_european_union boolean: Country EU membership status
country.names map<utf8_string>: Country name in all available languages
location.latitude double: Decimal latitude
location.longitude double: Decimal longitude
location.time_zone utf8_string: Name of timezone in the IANA Time Zone Database
location.weather_code utf8_string: Nearest international weather station code. These are as used by AOL Weather, The Weather Channel (weather.com), Yahoo! Weather and many more.
postal.code utf8_string: Zip / Postal code
subdivisions.geoname_id uint32: Unique ID of the administrative subdivision in the Geonames open database
subdivisions.iso_code utf8_string: ISO 3166-2 administrative division code
subdivisions.names map<utf8_string>: Administrative subdivision name in all available languages

Sample Data

Below is a sample output from the mmdblookup tool that show all available details for a given IP address :

~$ mmdblookup -f dbip-location.mmdb -i 8.8.8.8
  {
	"city":
      {
		"geoname_id":
          5375480 <uint32>
        "names":
          {
			"de":
              "Mountain View" <utf8_string>
			"en":
              "Mountain View" <utf8_string>
			"fa":
              "مانتین ویو" <utf8_string>
            "fr":
              "Mountain View" <utf8_string>
            "ja":
              "マウンテンビュー" <utf8_string>
            "ko":
              "마운틴뷰" <utf8_string>
            "ru":
              "Маунтин-Вью" <utf8_string>
            "zh-CN":
              "山景城" <utf8_string>
          }
      }
	"continent":
      {
        "code":
          "NA" <utf8_string>
		"geoname_id":
          6255149 <uint32>
		"names":
          {
            "de":
              "Nordamerika" <utf8_string>
            "en":
              "North America" <utf8_string>
            "es":
              "Norteamérica" <utf8_string>
            "fa":
              " امریکای شمالی" <utf8_string>
            "fr":
              "Amérique Du Nord" <utf8_string>
            "ja":
              "北アメリカ大陸" <utf8_string>
            "ko":
              "북아메리카" <utf8_string>
            "pt-BR":
              "América Do Norte" <utf8_string>
            "ru":
              "Северная Америка" <utf8_string>
            "zh-CN":
              "北美洲" <utf8_string>
          }
      }
    "country":
      {
		"geoname_id":
          6252001 <uint32>
		"is_in_european_union":
          false <boolean>
        "iso_code":
          "US" <utf8_string>
        "names":
          {
            "de":
              "Vereinigte Staaten von Amerika" <utf8_string>
            "en":
              "United States" <utf8_string>
            "es":
              "Estados Unidos de América (los)" <utf8_string>
            "fa":
              "ایالات متحدهٔ امریکا" <utf8_string>
            "fr":
              "États-Unis" <utf8_string>
            "ja":
              "アメリカ合衆国" <utf8_string>
            "ko":
              "미국" <utf8_string>
            "pt-BR":
              "Estados Unidos" <utf8_string>
            "ru":
              "США" <utf8_string>
            "zh-CN":
              "美国" <utf8_string>
          }
      }
	"location":
      {
        "latitude":
          37.422900 <double>
        "longitude":
          -122.085000 <double>
		"time_zone":
          "America/Los_Angeles" <utf8_string>
        "weather_code":
          "USCA0746" <utf8_string>
      }
	"postal":
      {
        "code":
          "94043" <utf8_string>
      }
    "subdivisions":
      [
        {
          "geoname_id":
            5332921 
          "iso_code":
            "CA" <utf8_string>
          "names":
            {
			  "de":
                "Kalifornien" 
			  "en":
                "California" 
			  "es":
                "California" 
              "fa":
                "کالیفرنیا" 
              "fr":
                "Californie" 
              "ja":
                "カリフォルニア州" 
              "ko":
                "캘리포니아 주" 
              "pt-BR":
                "Califórnia" 
              "ru":
                "Калифорния" 
              "zh-CN":
                "加利福尼亚州" 
			}
        }
		{
          "geoname_id":
            5393021 
          "names":
            {
              "de":
                "Santa Clara County" 
              "en":
                "Santa Clara County" 
              "es":
                "Condado de Santa Clara" 
              "fa":
                "شهرستان سانتا کلارا، کالیفرنیا" 
              "fr":
                "Comté de Santa Clara" 
              "ja":
                "サンタクララ郡" 
              "ko":
                "샌타클래라 군" 
              "pt-BR":
                "Condado de Santa Clara" 
              "ru":
                "Санта-Клара" 
              "zh-CN":
                "聖塔克拉拉縣" 
            }
        }
	  ]
  }

How To

You may read the IP to Location database and handle the data with your own code, or use it from existing software such as web servers.

Automatic updates

dbip-update is the preferred way for loading and updating databases. The tutorial below will guide you through installation, initial database download and setup of automatic updates :

Database fetch and update tutorial

Software Libraries

There are several free open-source MMDB reader libraries available for many development platforms :

Nginx

ngx_http_geoip2_module creates variables with values from a MMDB database based on the client IP (default) or from a specific variable (supports both IPv4 and IPv6).

The module now supports nginx streams and can be used in the same way the http module can be used.

Apache

mod_maxminddb allows you to query MMDB files from Apache 2.2+ using the libmaxminddb library.

Back to IP to Location

IP to Location MMDB format