The NaturalEarthCountry Database provides the country (or equivalent) for a given location (latitude and longitude). It's simple: you give latitude and longitude and the Database returns the country (sovereign or otherwise), dependency, disputed territory, lease, or no man's land. The response includes the formal, adminstrative, and short names for the entity, its sovereignty, its ISO-3166 two and three letter codes, two forms of postal abbreviations, and a few additional codes and statistics. For a complete listing of the data returned, please see the Returned Values Section below.

Unlike some other tools for accomplishing this task, AskGeo look-ups are based on an actual map of the world, rather than the "closest point of interest", which ensures accuracy.

The map data for the NaturalEarthCountry Database comes from the Natural Earth Project which publishes free vector and raster map data. In addition to repackaging that data in an easy-to-use format for Web developers and Java and .NET programmers, AskGeo also adds a high-performance spatial index that allows for extremely low-latency queries. Please see the Performance Section below for details on how fast this Database is.

Natural Earth Country Map

The map below was generated from the NaturalEarthCountry Database.

The colors for each country (or equivalent) have been selected randomly by sovereignty to provide contrast.

Database Statistics

The NaturalEarthCountry Database contains 253 distinct entities, made up of 4,001 polygonal shapes and defined by a total of 536,399 vertexes. The Database includes 188 sovereign countries, 21 non-sovereign countries, 36 dependencies, 2 disputed territories, 4 no-man's lands, and 2 leases.

Map Accuracy

The map data for the NaturalEarthCountry Database comes from the Natural Earth Project which publishes free vector and raster map data. Natural Earth describes the data as having a scale of 1:10,000,000 but they do not publish any error statistics. A casual sampling of the data in comparison to Google Maps suggests that the error is typically less than a kilometer. We are looking for more accurate sources for a higher fidelity version of this Database, but have not as yet found one.

Returned Values

The NaturalEarthCountry Database returns several parameters in response to a given query point. While all these parameters are returned with a single call to the Web API, for performance reasons the Java and .NET Libraries divide them into two separate groups.

The first group is common to all the Databases and pertains to the query point's relationship to the map region from which the returned values were drawn.

KeyDescriptionUnitsType
AskGeoId The internally-used AskGeo unique ID for the returned polygon n/aint
IsInside Whether or not the query point is inside the returned polygon n/aboolean
MinDistanceKm The distance from the query point to the nearest interior point of the returned polygon kilometersfloat

The second group is specific to this Database.

KeyDescriptionUnitsType
NaturalEarthCode Internal Natural Earth entity code similar to ISO-3166-3 but without gaps n/aString
NameSovereignty Name of the Country that has sovereignty over this entity (no gaps) n/aString
IsNotSovereign Indicates if this entity has its own sovereignty, 0: false, 1: true (no gaps) n/aint
EntityType Entity type: 'Country', 'Sovereign country', 'Dependency', 'Disputed', 'Indeterminate', or 'Lease' (no gaps) n/aString
NameAdministrative Administrative name (probably the most useful name all around, no gaps) n/aString
NameShort Short form name of entity, including common abbreviations, for example, 'Island' becomes 'Is.' (has gaps) n/aString
Abbreviation Long form abbreviation, for example, Berm., Rep. Congo, Cz. Rep. (has gaps) n/aString
AbbreviationPostal One, two, or three letter postal abbreviation (has gaps) n/aString
NameFormal Formal name (has gaps) n/aString
Notes Notes indicating sovereignty relationships, etc. (mostly blank) n/aString
NameSortable Name suitable for sorting (no gaps) n/aString
MapColorCode Color index from US State Department political world map where no neighboring country has the same color, but all territories of a sovereign country share the same color (no gaps) n/aint
TotalPopulation2009Estimate Estimated total population (2009, from UN and other sources, has gaps, missing values: -99) peoplefloat
TotalGdp2009Estimate Estimate total GDP in millions of dollars (2009, from World Bank and other sources, has gaps, missing values: -99) million dollarsfloat
Iso3166A2 ISO-3166-2 two-letter country code (has gaps, missing values: -99) n/aString
Iso3166A3 ISO-3166-3 three-letter country code (has gaps, missing values: -99) n/aString

No gaps = all entries in the Database have a value in this field.
Has gaps = NOT all entries in the Database have a value in this field, and you will need to check for blank / missing value codes as appropriate.

Java Library

All AskGeo Java Libraries are compatible with Java 6, have no external dependencies, and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures.

The libraries come in both double and single (float) precision versions, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

Java Documentation

There are only two classes that you need to be aware of to use the AskGeo NaturalEarthCountry Java Library.

class CountryMap

Contains map data and allows queries on the Database.

class CountryResult

Embodies the result of a query on a CountryMap instance.

They are described in further detail in the sections that follow.

The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo NaturalEarthCountry Java Library.

For full documentation of the classes included, please see the:

Full Java Docs

CountryMap

The CountryMap class stores the map data and exposes a query method to find the country (or equivalent) at a given latitude and longitude. Because each CountryMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.

class CountryMap {
static CountryMap create(InputStream dataFileStream)
Factory method for building a CountryMap instance.
  • InputStream dataFileStream: Input Stream of the Data File to be read to create this map
CountryResult findResult(float latDeg, float lonDeg)
Query method returns a CountryResult instance for a given latitude and longitude.
  • float latDeg: Latitude of the query point (degrees)
  • float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}

CountryResult

The CountryResult class embodies the result of a query on a CountryMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "get" followed by the "Key" parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, a few important accessors are:

class CountryResult {
String getNameShort()
Returns short name of the country or equivalent.
String getEntityType()
Returns the entity type: Country, Sovereign country, Dependency, Disputed, Indeterminate, or Lease.
String getIso3166A3()
Returns the ISO-3166-3 three-letter country code (has gaps, missing values: "-99").
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}

Java Example

The following is a complete example program demonstrating the use of the AskGeo NaturalEarthCountry Java Library.

import com.askgeo.flt.naturalearth.CountryMap;
import com.askgeo.flt.naturalearth.CountryResult;
import java.io.FileInputStream;

public class NaturalEarthExample {
    static float[][] examplePoints = {{37f, -122f}, {42f, -89f}, {52f, -1f}, {51f, -31f}};
    static String license = "INSERT YOUR LICENSE STRING HERE";
    static String dataFilePath = "askgeo-natural-earth-country-1.1.0.dat";

    public static void main(String[] args) {
        try {
            CountryMap map = CountryMap.create(new FileInputStream(dataFilePath));
            map.authorize(license);
            for (float[] point : examplePoints) {
                CountryResult result = map.findResult(point[0], point[1]);
                if (result != null) {
                    System.out.println(" Latitude: " + point[0] +
                            ", Longitude: " + point[1] +
                            ", Short name: " + result.getNameShort() +
                            ", Formal name: " + result.getNameFormal());
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}

Java Library Performance and Memory Consumption

AskGeo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the AskGeo Java Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.

We tested the performance of the Library using a single thread on a computer with an Intel Core i7 3.33 GHz running 64-bit Windows 7. For each version of the library, we tested:

Construction Time

The time it took to construct an instance of the NaturalEarthCountry Database object.

Per-Query Time

The average response time for a single query. This was measured by running 100,000 queries, randomly distributed over the full extent of the map.

Memory

Resident memory of a NaturalEarthCountry Database instance, as estimated by measuring the JVM's used memory after running the GC when running a simple test application containing only the map. This will lead to a slight over-estimate of the resident memory because it will include the overhead of the test application.

Data File Size

The file size of the Data File associated with this Database.

PrecisionConstruction TimePer-Query TimeMemoryData File Size
Single 0.85 seconds 1.85e-04 seconds 8.7 MB5.3 MB
Double 0.86 seconds 1.95e-04 seconds 12.7 MB5.3 MB

.NET Library

All AskGeo .NET Libraries are compatible with .NET 4 and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures. Except for a few small changes to be more consistent with .NET style and coding conventions, the AskGeo .NET Libraries are a direct port of the AskGeo Java Libraries.

Where relevant both double and single (float) precision versions of the various classes are provided, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

.NET Documentation

There are only two classes that you need to be aware of to use the AskGeo NaturalEarthCountry .NET Library.

class CountryMap

Contains map data and allows queries on the Database.

class CountryResult

Embodies the result of a query on a CountryMap instance.

They are described in further detail in the sections that follow.

The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo NaturalEarthCountry .NET Library.

For full documentation of the classes included, please see the:

Full .NET Docs

CountryMap

The CountryMap class stores the map data and exposes a query method to find the country (or equivalent) at a given latitude and longitude. Because each CountryMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.

class CountryMap {
static CountryMap Create(Stream dataFileStream)
Factory method for building a CountryMap instance.
  • Stream dataFileStream: Input Stream of the Data File to be read to create this map
CountryResult FindResult(float latDeg, float lonDeg)
Query method returns a CountryResult instance for a given latitude and longitude.
  • float latDeg: Latitude of the query point (degrees)
  • float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

CountryResult

The CountryResult class embodies the result of a query on a CountryMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "Get" followed by the "Key" parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, a few important accessors are:

class CountryResult {
String GetNameShort()
Returns short name of the country or equivalent.
String GetEntityType()
Returns the entity type: Country, Sovereign country, Dependency, Disputed, Indeterminate, or Lease.
String GetIso3166A3()
Returns the ISO-3166-3 three-letter country code (has gaps, missing values: "-99").
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

.NET Example

The following is a complete example program demonstrating the use of the AskGeo NaturalEarthCountry .NET Library.

using System;
using System.IO;
using AskGeo.Flt;

class NaturalEarthCountry {
    static void Main(string[] args) {
        float[,] examplePoints = { { 37f, -122f }, { 42f, -89f }, { 52f, -1f }, { 51f, -31f } };
        String license = "INSERT YOUR LICENSE STRING HERE";
        String dataFilePath = @"askgeo-natural-earth-country-1.1.0.dat";
        NaturalEarthCountryMap map = NaturalEarthCountryMap.Create(new FileStream(dataFilePath, FileMode.Open));
        map.Authorize(license);

        for (int i = 0; i < examplePoints.GetLength(0); i++) {
            NaturalEarthCountryResult result = map.FindResult(examplePoints[i, 0], examplePoints[i, 1]);
            if (result != null) {
                Console.WriteLine(" Latitude: " + examplePoints[i, 0] +
                            ", Longitude: " + examplePoints[i, 1] +
                            ", Short name: " + result.GetNameShort() +
                            ", Formal name: " + result.GetNameFormal());
            }
        }
    }
}

.NET Library Performance and Memory Consumption

AskGeo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the AskGeo .NET Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.

The AskGeo Libraries were originally designed and written in Java and ported to .NET. Consequently, detailed performance and memory consumption information is available for the Java Libraries but not for the .NET Libraries. We have run spot checks on a few of our test cases and found that the .NET Libraries have essentially the same performance characteristics as the Java Libraries. This is unsurprising given the similarities between the languages and the virtual machines on which they run. See the Java Performance Section for detailed information on construction time, per-query time, and memory consumption.