Basic Types

This section describes the classes of basic data types that are often found in the pages of maps API guide and required for use with many maps API objects.

DG.LatLng

Represents a geographical point with a certain latitude and longitude.

var latlng = DG.latLng(54.98, 82.89);

All methods that accept LatLng objects also accept them in a simple Array form and simple object form (unless noted otherwise), so these lines are equivalent:

map.panTo([54.98, 82.89]);
map.panTo({lon: 82.89, lat: 54.98});
map.panTo({lat: 54.98, lng: 82.89});
map.panTo(DG.latLng(54.98, 82.89));

Constructor

Factory Description
DG.latLng( <Number> latitude, <Number> longitude, <Number> altitude? ) Creates an object representing a geographical point with the given latitude and longitude (and optionally altitude).
DG.latLng( <Array> coords ) Expects an array of the form [Number, Number] or [Number, Number, Number] instead.
DG.latLng( <Object> coords ) Expects an plain object of the form {lat: Number, lng: Number} or {lat: Number, lng: Number, alt: Number} instead.

Methods

Method Returns Description
equals( <LatLng> otherLatLng, <Number> maxMargin? ) Boolean Returns true if the given LatLng point is at the same position (within a small margin of error). The margin of error can be overriden by setting maxMargin to a small number.
toString() String Returns a string representation of the point (for debugging purposes).
distanceTo( <LatLng> otherLatLng ) Number Returns the distance (in meters) to the given LatLng calculated using the Haversine formula.
wrap() LatLng Returns a new LatLng object with the longitude wrapped so it's always between -180 and +180 degrees.
toBounds( <Number> sizeInMeters ) LatLngBounds Returns a new LatLngBounds object in which each boundary is sizeInMeters meters apart from the LatLng.

Properties

Property Type Description
lat Number Latitude in degrees.
lng Number Longitude in degrees.
alt Number Altitude in meters (optional).

DG.LatLngBounds

Represents a rectangular geographical area on a map.

var southWest = DG.latLng(54.9801, 82.8974),
    northEast = DG.latLng(54.9901, 82.9074),
    bounds = DG.latLngBounds(southWest, northEast);

All methods that accept LatLngBounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

map.fitBounds([
    [54.9801, 82.8974],
    [54.9901, 82.9074]
]);

Creation

Factory Description
DG.latLngBounds( <LatLng> southWest, <LatLng> northEast ) Creates a LatLngBounds object by defining south-west and north-east corners of the rectangle.
DG.latLngBounds( <LatLng[]> latlngs) Creates a LatLngBounds object defined by the geographical points it contains. Very useful for zooming the map to fit a particular set of locations with fitBounds.

Methods

Method Returns Description
extend( <LatLng> latlng ) this Extend the bounds to contain the given point.
extend( <LatLngBounds> otherBounds ) this Extend the bounds to contain the given bounds.
pad( <Number> bufferRatio ) LatLngBounds Returns bigger bounds created by extending the current bounds by a given percentage in each direction.
getCenter() LatLng Returns the center point of the bounds.
getSouthWest() LatLng Returns the south-west point of the bounds.
getNorthEast() LatLng Returns the north-east point of the bounds.
getNorthWest() LatLng Returns the north-west point of the bounds.
getSouthEast() LatLng Returns the south-east point of the bounds.
getWest() Number Returns the west longitude of the bounds.
getSouth() Number Returns the south latitude of the bounds.
getEast() Number Returns the east longitude of the bounds.
getNorth() Number Returns the north latitude of the bounds.
contains( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle contains the given one.
contains( <LatLng> latlng ) Boolean Returns true if the rectangle contains the given point.
intersects( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
overlaps( <Bounds> otherBounds ) Boolean Returns true if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.
toBBoxString() String Returns a string with bounding box coordinates in a 'southwest_lng,southwest_lat,northeast_lng,northeast_lat' format. Useful for sending requests to web services that return geo data.
equals( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle is equivalent (within a small margin of error) to the given bounds.
isValid() Boolean Returns true if the bounds are properly initialized.

DG.Point

Represents a point with x and y coordinates in pixels.

var point = DG.point(200, 300);

All methods and options that accept Point objects also accept them in a simple Array form (unless noted otherwise), so these lines are equivalent:

map.panBy([200, 300]);
map.panBy(DG.point(200, 300));

Creation

Factory Description
DG.point( <Number> x, <Number> y, <Boolean> round? ) Creates a Point object with the given x and y coordinates. If optional round is set to true, rounds the x and y values.
DG.point( <Number[]> coords) Expects an array of the form [x, y] instead.

Methods

Method Returns Description
clone() Point Returns a copy of the current point.
add( <Point> otherPoint ) Point Returns the result of addition of the current and the given points.
subtract( <Point> otherPoint ) Point Returns the result of subtraction of the given point from the current.
divideBy( <Number> num ) Point Returns the result of division of the current point by the given number.
multiplyBy( <Number> num ) Point Returns the result of multiplication of the current point by the given number.
scaleBy( <Point> scale ) Point Multiply each coordinate of the current point by each coordinate of scale. In linear algebra terms, multiply the point by the scaling matrix defined by scale.
unscaleBy( <Point> scale ) Point Inverse of scaleBy. Divide each coordinate of the current point by each coordinate of scale.
round() Point Returns a copy of the current point with rounded coordinates.
floor() Point Returns a copy of the current point with floored coordinates (rounded down).
ceil() Point Returns a copy of the current point with ceiled coordinates (rounded up).
distanceTo( <Point> otherPoint ) Number Returns the cartesian distance between the current and the given points.
equals( <Point> otherPoint ) Boolean Returns true if the given point has the same coordinates.
contains( <Point> otherPoint ) Boolean Returns true if both coordinates of the given point are less than the corresponding current point coordinates (in absolute values).
toString() String Returns a string representation of the point for debugging purposes.

Properties

Property Type Description
x Number x coordinate.
y Number y coordinate.

DG.Bounds

Represents a rectangular area in pixel coordinates.

var p1 = DG.point(10, 10),
    p2 = DG.point(40, 60),
    bounds = DG.bounds(p1, p2);

All methods that accept Bounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

otherBounds.intersects([[10, 10], [40, 60]]);

Creation

Factory Description
DG.bounds( <Point> topLeft, <Point> bottomRight ) Creates a Bounds object from two coordinates (usually top-left and bottom-right corners).
DG.bounds( <Point[]> points ) Creates a Bounds object from the points it contains.

Methods

Method Returns Description
extend( <Point> point ) this Extends the bounds to contain the given point.
getCenter( <Boolean> round? ) Point Returns the center point of the bounds.
getBottomLeft() Point Returns the bottom-left point of the bounds.
getTopRight() Point Returns the top-right point of the bounds.
getSize() Point Returns the size of the given bounds.
contains( <Bounds> otherBounds ) Boolean Returns true if the rectangle contains the given one.
contains( <Point> point ) Boolean Returns true if the rectangle contains the given poing.
intersects( <Bounds> otherBounds ) Boolean Returns true if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
overlaps( <Bounds> otherBounds ) Boolean Returns true if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.

Properties

Property Type Description
min Point The top left corner of the rectangle.
max Point The bottom right corner of the rectangle.