City Database Files

To obtain information about cities using STK database files, use the StkCityDatabase class. This type uses a directory and a base filename to identify a set of files with the same name, but differing extensions, which together define the database. For more information on the format of these files, see the section on the database format below.

City Databases in DME Component Libraries

After instantiating an instance of StkCityDatabase, queries can be made to obtain a set of cities matching a set of criteria. The following example demonstrates how to query the database for cities:

Java

Copy

StkCityDatabase db = new StkCityDatabase(dbDirectory, "stkCityDb");

// Create a query object and then populate it with the properties to query on.
// Regular expressions are used to query on strings.
StkCityDatabaseQuery query = new StkCityDatabaseQuery();
query.setCityName(Pattern.compile("Philadelphia"));

// only look in PA, because there's also a New Philadelphia in Ohio
query.setProvinceName(Pattern.compile("Pennsylvania"));

// Get the database entries matching the query and print out the Longitude and Latitude of each.
for (StkCityDatabaseEntry entry : db.getEntries(query)) {
    System.out.format("%s: Longitude %f, Latitude %f%n", entry.getCityName(), entry.getLongitude(), entry.getLatitude());
}

City Database Format

A city database is comprised of a total of three files which have the same base filename with different file extensions. The file extension determines the type of data contained by that file. Not all files are required. If an optional data file is not present, then that information will be silently omitted from the database entries.

File	Contents	Required?
stkCityDb.cd	Main database file	Required
stkCityDb.cc	Countries, City Types, Central Bodies	Optional
stkCityDb.gd	Generic database information	Optional

The first file contains fixed-width fields, where one row represents a single entry. The remaining contain a standard text format.

stkCityDb.cd File

This is the main city database file; it contains all searchable fields. The format, starting at column zero, is as follows:

Column	Width	Description
0-6	7	City Key. Unique integer identifier
7-36	30	City Name
37-38	2	City Type: 1 - Populated Place 2 - Administration Center 3 - National Capital
39-58	20	Country
59-98	40	Province/State
99-101	3	Province Rank
102-112	11	Population
113-115	3	Population Rank
116-132	17	Latitude (in degrees)
133-149	17	Longitude (in degrees)
151-162	12	Central Body

stkCityDb.cc File

This is the country and city type file. It contains a list of all the valid countries, city types, and central bodies for the database, and defines the lists returned from the getCountries, and getCityTypes, and getCentralBodies methods.

Example stkCityDb.cc file, abbreviated

Copy

Begin Country
ARGENTINA
AUSTRALIA
AUSTRIA
UNITED KINGDOM
URUGUAY
USA
WESTERN SAMOA
End Country

Begin Type
        Populated Place
        Administration Center
        National Capital
End Type

Begin Central_Body
Earth
End Central_Body

stkCityDb.gd File

This is the generic database file, which contains version information and the date of last update of the database. This information is returned from the Version (get) and LastUpdateDate (get) properties.

Example stkCityDb.gd file

Copy

BEGIN DatabaseUpdate
Version 1.0
LastUpdate 20110711
END DatabaseUpdate

Creating Platforms for Cities

In order to use city information in other analysis in DME Component Libraries, it is useful to create a Platform object which represents the city. To make this easy, static methods are defined in StkCityDatabaseEntryExtensions and StkCityDatabaseExtensions that create a platform from a single database entry, or create a list of platforms for all entries matching a query, as the following example demonstrates:

Java

Copy

for (StkCityDatabaseEntry entry : db.getEntries(query)) {
    // A Platform object can be created from a single database entry.
    Platform platform = StkCityDatabaseEntryExtensions.createPlatform(entry);
}
// Or, a list of Platforms can be created from all entries matching a query.
ArrayList<Platform> platforms = StkCityDatabaseExtensions.createPlatforms(db, query);