Point, a standard type

A position on Earth: its latitude, its longitude and, if you know it, its height.

Use it for anywhere you'd drop a pin, such as a shop or a delivery drop-off. For a path, use LineString. For an area, use Polygon. For an address someone can post to, use PostalAddress.

Shape

Field	Type	Required?
`latitude`	`Latitude`	Yes
`longitude`	`Longitude`	Yes
`altitude`	`Length`	No

Write every field when you build one, and give a field that isn't required as none.

Example

example

Point { latitude: 51.5072 longitude: -0.1276 altitude: none }

These operations give one: geo.centroid, geo.from_lat_lng and geo.from_lng_lat.

Good to know

Fields are named, so latitude and longitude can't be swapped by accident. In JSON they follow GeoJSON's order, longitude first.
geo.distance gives the distance between two, and a route takes and returns one as GeoJSON.
== tells you whether two are the same. < and list.sort_by don't take it, so sort by one of its parts instead.

In JSON

A GeoJSON geometry, with each position's longitude first, in a request, a response or json.write:

json

{"type":"Point","coordinates":[-0.1276,51.5072]}{"type":"Point","coordinates":[151.2093,-33.8688]}{"type":"Point","coordinates":[0,0]}

When you read one, a field that isn't required may be left out, or sent as null.

Details

Text form, storage, how it is shown, and operations

Point is in the group Geospatial, and has been in Jadpo since 0.1.0.

Text form

It has no single text form, so text.from and text.parse don't take it.

How it is stored

It is stored in one column named for the field, of type geography. {"type":"Point","coordinates":[0,0]} is stored as 'SRID=4326;POINT (0 0)'::geography.

How it is shown to people

text.format(value, locale:) shows it to people in their locale.

With locale: Locale.en_gb:

Value	Shown
`{"type":"Point","coordinates":[-0.1276,51.5072]}`	`51.5072° N, 0.1276° W`
`{"type":"Point","coordinates":[151.2093,-33.8688]}`	`33.8688° S, 151.2093° E`
`{"type":"Point","coordinates":[0,0]}`	`0°, 0°`
`{"type":"Point","coordinates":[-180,-90]}`	`90° S, 180° W`
`{"type":"Point","coordinates":[86.925,27.9881,8848.86]}`	`27.9881° N, 86.925° E, 8,848.86 m`

Operations

geo.bearing(from: Point, to: Point) -> Bearing: The direction the geodesic leaves from in, in degrees clockwise from true north, at least 0 and below 360, to 9 places. Two equal points have none: the call fails with same_point, which its attempt maps.
geo.bounding_box(shape: T) -> BoundingBox: The smallest box of parallels and meridians holding the shape, an edge's highest or lowest point counted, across the antimeridian when that box is narrower; a shape holding a pole runs from -180 to 180.
geo.centroid(shape: T) -> Point: The shape's centre on the sphere, as PostGIS's ST_Centroid(x, false) finds it: each point a unit vector, weighted by area, length or count by the shape's kind, summed, and back to latitude and longitude. It may lie outside a concave polygon.
geo.contains(a: T, b: U) -> Bool: Whether no point of b lies outside a, edges included. a may be a BoundingBox, whose sides are compared directly, or a Circle, holding the points within its radius of its centre.
geo.distance(from: Point, to: Point) -> Length: The geodesic distance between two points on the ellipsoid, rounded half to even to the micrometre.
geo.from_lat_lng(numbers: List<Number>) -> Point: The Point two numbers give, latitude first, as [51.5072, -0.1276], or three, the third its altitude in metres. A latitude past 90 or a longitude past 180 fails with out_of_range, and any other count of numbers with malformed, which the call's attempt maps.
geo.from_lng_lat(numbers: List<Number>) -> Point: The Point two numbers give, longitude first, as GeoJSON writes a position, [-0.1276, 51.5072], or three, the third its altitude in metres. A longitude past 180 or a latitude past 90 fails with out_of_range, and any other count of numbers with malformed, which the call's attempt maps.
geo.intersects(a: T, b: U) -> Bool: Whether the two share at least one point, edges included.
geo.to_wkt(shape: T) -> Text: The shape as WKT, longitude first, as PostGIS's ST_AsText writes it: POINT(-0.1276 51.5072), POINT Z (-0.1276 51.5072 35) with an altitude, each ring in the order it holds its points.
geo.within(a: T, b: U, distance: Length?) -> Bool: geo.contains(b, a); or, with distance:, whether two points are at most that far apart, as geo.distance measures them.

It also takes text.format, json.read, json.write and ==. How every standard type behaves says how they work.