Feature Read Requests


A feature is a point, polygon, or polyline, with associated metadata. A feature is always contained in a vector table and is referenced by its table ID and its own feature ID.

Features are queried by making a request to their table's endpoint, along with optional search criteria. Search criteria uses a SQL-like query language, which can create equations from the values of any table column as well as calculated geometric values.


Feature read requests are HTTP GET requests to the following URL:


where {tableId} is the ID of the specific table you're addressing. Read the Table section of Asset read requests for information on obtaining table IDs.

Individual features can be accessed by specifying their ID as follows:


Requests for individual features support the select and version parameters only.

Because table IDs are unique across the Google Maps Engine API, no projectId parameter needs to be included. As with all requests, an OAuth 2.0 token needs to be included as the value of an Authorization header. Read Making Requests for more information.


The Google Maps Engine API supports a limited SQL-like query language for requesting table features. A SQL-like predicate can be passed as the value of the where parameter, as follows:

GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features?where=age>10

The predicate must include a column name from the specified table (age in the example above) and a supported operator:

< Less than
> Greater than
= Equal to
<> Does not equal
<= Less than or equal to
>= Greater than or equal to
CONTAINS Contains the string

Predicates can be joined with AND and/or OR (note that AND has precedence over OR):

where=age>10 AND income<=50000

You may use a supported geometry function:

where=ST_DISTANCE(geometry,ST_POINT(1.23,4.56)) > 100

String comparisons can use any of the operators. Mathematical operators use alphabetical ordering on strings: B is greater than A. CONTAINS searches for the supplied string and will return true if the string is contained anywhere within a cell's contents. For example:

where=name CONTAINS 'sam'

matches sam, samuel, and flotsam. Note that the operand in any string comparison must be enclosed in single quotes:


If the string contains a single quote or a backslash, these must be escaped using a backslash. For example, C:\docs\mike's_list.txt becomes:


As with all parts of a request URL, predicates must be URL-encoded:


Examples in this documentation are not encoded, for ease of reading.

Geographic restrictions

Feature queries can be restricted to a specific geographic area, by passing a polygon, circle, line, or point to the intersects parameter.

The intersects restrictor is applied to the initial query to the Maps Engine server; any additional select or where restrictions are applied after the intersects results have been calculated.

Geometries are specified using a subset of the well-known text syntax. A custom CIRCLE syntax is also supported.


To specify a polygon:

  • Use the POLYGON syntax: intersects=POLYGON((v1_lng v1_lat, v2_lng v2_lat,...))
  • Vertices must be specified in a counter-clockwise order.
  • The first and last vertices must be identical; polygons will not be auto-closed.
  • You may create a polygon with up to 50 vertices (49 distinct points).
  • The polygon must have at least 4 vertices (3 distinct points).
  • Complex polygons are not supported (eg. polygons containing an inner polygon).
GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features
  ?intersects=POLYGON((-0.42 51.72, -0.49 51.33, 0.15 51.30, 0.27 51.51, 0.08 51.69, -0.42 51.72))


To specify a point:

  • Use the POINT syntax: intersects=POINT(lng lat)
GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features
  ?intersects=POINT(-0.177364 51.532053)


To specify a circle:

  • Use the CIRCLE syntax (not part of the well-known text syntax, but supported in the Google Maps Engine API): intersects=CIRCLE(center_lng center_lat, radius)
  • Pass the lng/lat coordinates of the center of the circle, along with the radius in meters.
GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features
  ?intersects=CIRCLE(18.068 59.328, 10000)


To specify a linestring:

  • Use the LINESTRING syntax: intersects=LINESTRING(pt1_lng pt1_lat, pt2_lng pt2_lat,...)
  • Your linestring may consist of up to 50 points.
GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features
  ?intersects=LINESTRING(173.96 -41.51, 174.15 -41.78, 173.93 -42.152, 173.67 -42.41)

Selecting response columns

Feature list requests can contain a select parameter that defines the data to include in the response. The select parameter accepts column names:

select=geometry,name,"opening hours"

You may also use a supported geometry function and a column alias:

select="opening hours",ST_DISTANCE(geometry,ST_POINT(1,2)) AS distance

A column alias may not contain spaces or other special characters, and must not be enclosed in quotes.

The response includes only the specified columns, in the same order as they are specified.

When using the select parameter, note the following:

  • Column names are case-sensitive.
  • All column names must be enclosed with double quotes, unless they:
    • Start with a letter or an underscore, AND
    • Contain letters, numbers, and/or underscores only.
    • For example, select=prop_1 or select="Property One".
  • If a column name includes quotation marks or backslashes, these must be escaped with a backslash (e.g. select="Property \"Hello!\"").
  • The geometry column that occurs first in the list will be shown in the geometry field of the GeoJSON output.
  • The request must not specify duplicate or non-existent columns.
  • If there are no geometry columns in the list, the geometry field will be null.

Limiting the response size

When requesting a list of features, the limit parameter applies an upper bound to the number of features returned, regardless of the number of pages.

For example, setting limit=500 will return up to 500 features.

The returned features may span multiple pages. Refer to the Pagination section to learn about retrieving results across more than one page.


When requesting a list of features in a table, you may specify an orderBy value that determines the order in which features are returned.

GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features
  ?select=ST_DISTANCE(geometry,ST_POINT(1,2)) AS distance
  &orderBy=distance DESC

The following rules apply to ordering:

  • Only one order key is supported.
  • The key must be defined in the SELECT clause. You may assign values to a temporary column alias (in this case distance):

    select=ST_DISTANCE(geometry,ST_POINT(1,2)) AS distance

    Or you may select an existing column in the table:

  • The sort order is stable. Features with identical keys are sorted by their primary key.
  • Sorting defaults to ascending order. You may append ASC or DESC to the orderBy clause to specify an order.

    select=age&orderBy=age DESC
  • When including an orderBy parameter, you must also include a limit parameter, whose value is less than or equal to 75.


When requesting a list of features, the maxResults parameter applies an upper bound to the number of features returned per page. To limit the number of features returned in total, use the limit parameter.

If more features match the query than fit on a page, a nextPageToken is included in the response. To retrieve additional results, repeat the request, passing the nextPageToken as the value of a pageToken URL parameter.

For example:

GET https://www.googleapis.com/mapsengine/v1/tables/tableId/features

A pageToken value is valid for 30 minutes from its construction.

Geometry functions

The following geometry functions are supported in where and select statements.

Relationship functions

  • ST_DISTANCE: Calculates the shortest distance in meters between two geometries. Distance is calculated over a perfect sphere with a circumference of 6,371,009 meters. Accepts a geometry column name and a geometry value, which may be the result of geometry constructors.

  • ST_INTERSECTS: Returns all features that intersect the described polygon. Accepts a geometry column name and a geometry value, which may be the result of geometry constructors.

    ST_INTERSECTS(geometry,ST_GEOMFROMTEXT('POLYGON ((1 3, 1 1, 4 1, 4 4, 1 3))'))


  • ST_POINT: Creates a point from a longitude and latitude value (in that order).

  • ST_GEOMFROMTEXT: Creates a geometry from a well-known text string literal.
    ST_GEOMFROMTEXT('LINESTRING (1 4, 2 1, 4 2)')

    Polygons must be specified in counter-clockwise order.

    ST_GEOMFROMTEXT('POLYGON ((1 4, 1 1, 4 1, 4 4, 1 4),
    (2 3, 2 2, 3 2, 3 3, 2 3))')


A feature list response returns a FeatureCollection object containing an array of features. For example:

GET https://www.googleapis.com/mapsengine/v1/tables/06673056454046135537-02851592172142513880/features
Authorization: Bearer {token}

The response:

  "type": "FeatureCollection",
  "features": [
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
      "properties": {
        "kml_name": "Stora Essingen",
        "kml_description": "http://en.wikipedia.org/wiki/Stora_Essingen",
        "gx_id": "1"
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
      "properties": {
        "kml_name": "Lilla Essingen",
        "kml_description": "http://en.wikipedia.org/wiki/Lilla_Essingen",
        "gx_id": "2"

    ... snip ...


The following information applies:

  • Integers are 64-bit signed integers that are encoded as strings in the JSON response and must also be encoded as strings in the request. For example, "123".
  • Doubles are encoded as JSON numbers. For example, 1.2345.
  • Strings are encoded as UTF-8.

Send feedback about...

Google Maps Engine API (Deprecated)