db.Geo | Weixin public doc

# db.Geo

The object contains a geographical location constructor. To perform a geographical location-based query, an index must be added to the place where the geographical location is stored. For details, see the geographical location chapter in Database Guidelines.

When using the geographical location API, in addition to the following geographical location constructors, you can also use the GeoJSON notation. Objects constructed using a geographical location constructor can call the toJSON method to get equivalent GeoJSON pure JS object. If the geographical location field exists in the query result, then the geographical location object, instead of the GeoJSON object, is returned.

db.Geo contains the following fields:

Field	Description
Point	Point
LineString	Line segment
Polygon	Polygon
MultiPoint	Point set
MultiLineString	Line segment set
MultiPolygon	Polygon set

# db.Geo.Point

Constructs a "point" for a geographic location.

The method signature is shown as below:

function Point(longitude: number, latitude: number): Point

The method accepts two required parameters: longitude and latitude. Be sure to note the order.

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.Point(113, 23)
    }
  })
}

Besides using a point constructed via API, you can also use the Point of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "Point",
  "coordinates": [longitude, latitude] // Array of numbers: [longitude, latitude]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'Point',
        coordinates: [113, 23]
      }
    }
  })
}

# db.Geo.LineString

Constructs a "line segment" for a geographical location. A line segment consists of two or more orderly connected points.

The method signature is shown as below:

function LineString(points: Point[]): LineString

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.LineString([
        db.Geo.Point(113, 23),
        db.Geo.Point(120, 50),
        // ... More points are supported
      ])
    }
  })
}

Besides using a line segment constructed via API, you can also use the LineString of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "LineString",
  "coordinates": [
    [p1_lng, p1_lat],
    [p2_lng, p2_lng]
    // ... More points are supported
  ]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'LineString',
        coordinates: [
          [113, 23],
          [120, 50]
        ]
      }
    }
  })
}

# db.Geo.Polygon

Construct a "polygon" for a geographic location. A polygon consists of one or more Linear Rings. A linear ring is a closed line segment, which consists of at least four points, where the coordinates of the last point and those of the first point must be the same, indicating the start and end points of the ring. If a polygon consists of multiple linear rings, the first one is the outer ring (outer boundary), and others are inner rings (i.e. the holes within the outer ring, excluding the area in this polygon). If a polygon consists of only one linear ring, then it is the outer ring.

Polygon construction rules:

The first linear ring must be the outer ring
The outer ring cannot be self-intersecting
All inner rings must be completely inside the outer ring
Inner rings cannot intersect or overlap, nor can they have a common side.

The method signature is shown as below:

function Polygon(lineStrings: LineString[]): Polygon

Sample code: Single-ring polygon

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: Polygon([
        LineString([
          Point(0, 0),
          Point(3, 2),
          Point(2, 3),
          Point(0, 0)
        ])
      ])
    }
  })
}

Sample code: Polygon having an outer ring and an inner ring

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: Polygon([
        // Outer ring
        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
        // Inner ring
        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
      ])
    }
  })
}

Besides using a polygon constructed via API, you can also use the Polygon of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "Polygon",
  "coordinates": [
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // Outer ring
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // Optional inner ring 1
    ...
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // Optional inner ring n
  ]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'Polygon',
        coordinates: [
          [ [0, 0], [30, 20], [20, 30], [0, 0] ],
          [ [10, 10], [16, 14], [14, 16], [10, 10]]
        ]
      }
    }
  })
}

# db.Geo.MultiPoint

Construct a "point" set for a geographic location. A point set consists of one or more points.

The method signature is shown as below:

function MultiPoint(points: Point[]): MultiPoint

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.MultiPoint([
        db.Geo.Point(113, 23),
        db.Geo.Point(120, 50),
        // ... More points are supported
      ])
    }
  })
}

Besides using a point set constructed via API, you can also use the MultiPoint of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "MultiPoint",
  "coordinates": [
    [p1_lng, p1_lat],
    [p2_lng, p2_lng]
    // ... More points are supported
  ]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiPoint',
        coordinates: [
          [113, 23],
          [120, 50]
        ]
      }
    }
  })
}

# db.Geo.MultiLineString

Construct a "line segment" set for a geographic location. A line segment set consists of multiple line segments.

The method signature is shown as below:

function MultiLineString(lineStrings: LineString[]): MultiLineString

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { LineString, MultiLineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: MultiLineString([
        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
      ])
    }
  })
}

Besides using a polygon set via API, you can also use the MultiPolygon of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "MultiLineString",
  "coordinates": [
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
    ...
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
  ]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiLineString',
        coordinates: [
          [ [0, 0], [3, 3] ],
          [ [5, 10], [20, 30]]
        ]
      }
    }
  })
}

# db.Geo.MultiLineString

Construct a "polygon" set for a geographic location. A line polygon set consists of multiple polygons.

The method signature is shown as below:

function MultiPolygon(polygons: Polygon[]): MultiPolygon

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { MultiPolygon, Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: MultiPolygon([
        Polygon([
          LineString([ Point(50, 50), Point(60, 80), Point(80, 60), Point(50, 50) ]),
        ]),
        Polygon([
          LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
          LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
        ]),
      ])
    }
  })
}

Besides using a polygon set via API, you can also use the MultiPolygon of an equivalent GeoJSON represented in JSON as follows:

{
  "type": "MultiPolygon",
  "coordinates": [
    // polygon 1
    [
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      ...
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
    ],
    ...
    // polygon n
    [
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      ...
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
    ],
  ]
}

Sample code

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiPolygon',
        coordinates: [
          [
            [ [50, 50], [60, 80], [80, 60], [50, 50] ]
          ],
          [
            [ [0, 0], [30, 20], [20, 30], [0, 0] ],
            [ [10, 10], [16, 14], [14, 16], [10, 10]]
          ]
        ]
      }
    }
  })
}