A pdLocation object specifies a specific position on the Earth’s surface. The shape of the Earth is sufficiently close to being spherical that positions on its surface can be defined using spherical coordinates. In this case, given only as latitude and longitude angles as distance is already assumed to be Earth’s radius.

In addition to its defining properties, a geographic location also has derivative properties such as its time zone and elevation above sea level, though these are also governed by geopolitical boundaries and local terrain.

Given that a location can be used to represent an entire city or a single house within that city, additional associated properties such a location name, state, zipcode/postcode or country are primarily informational in nature and useful for presentation or geolocation purposes.


A Geographic location has the following properties, each explained in more detail below:


Terrestrial latitude is a defining property given as the angle from the Earth’s center between the given location and the plane of the equator, where angles above the equator (towards the North Pole) are positive and angles below the equator (towards the South Pole) are negative. Latitude angles are always measured along the plane passing through the location as well as both poles and the Earth’s center, and are typically given in degrees.

Figure 1 - Lines of terrestrial latitude on the Earth's surface.

Latitude angles define the relative directions of North and South on the Earth’s surface, where the direction of increasing latitude is North whilst decreasing latitude is South.


Terrestrial longitude is a defining property given as the angle between two planes which both pass through the Earth’s centre and both poles. The reference plane passes through Greenwich in the United Kingdom and the second plane passed through the actual location point. Longitude angles are always measured parallel to the equator, and are typically given in degrees. The line of this reference plane on the Earth’s surface is known as the prime meridian and defines the line of zero longitude.

Figure 1 - Lines of terrestrial longitude on the Earth's surface.

Longitude angles define the relative directions of East and West on the Earth’s surface, where the direction of increasing longitude is East whilst decreasing longitude is West.


The Earth rotates around its own axis at a relatively constant speed such that the Sun, when viewed from the Earth’s center, traverses the full 360 degrees of longitude in exactly 24 hours. It is important to state it this way as the center of the Earth over the course of that day will also have rotated around the Sun by 0.98563 degrees (given that it orbits 360 degrees around the Sun every 365.25 days), so the rotation of the Earth relative to its own axis every 24 hours will actually be closer to 361 degrees.

Thus there is a linear relationship between solar angle and terrestrial longitude, such that solar time increases by 1 hour every 15 degrees of longitude (360 degrees / 24 hours). This means that sunrise and sunset at any two locations will occur at different times, with the difference in decimal hours being the difference of their longitudes divided by 15 degrees.

In order to syncronise local times at different locations, regional time zones are used. A time zone is given in decimal hours as an offset from the current time at the prime meridian, usually refered to as UTC. The time zone at any particular location is a derivative property that is also based on the geopolitical region in which it sits as countries and states set their own local time zones.

As the boundaries of geopolitical regions are often very complex, it is not a trivial matter to derive the time zone for any location solely from its latitude and longitude. It is possible to use a time-zone map, however their resolution is often limited so locations very close to boundaries may not always be absolutely correct.


See also: Great video to emulate in real-time.


Elevation is the height of the given location above sea level. This value is based on the local terrain and can be used to when calculating atmospheric pressure effects or sky turbidity.


Gives the location a human readable name. This is an


set(latitude, longitude, timezone);

    latitude: -32.0,
    longitude: -116.0,
    timezone: 8.0