Click here to see your recently viewed pages and most viewed pages.
Hide
Google Maps Engine API (Deprecated)

Creating an Empty Table

Tables in the Google Maps Engine API contain vector features. You can create a new table by sending the table metadata to the Maps Engine service.

Overview

The Google Maps Engine API provides two ways of creating a new table asset:

  • Create an empty table, by specifying a schema and metadata in the request body.
  • Upload a table data file and associated sidecar files. This method is covered in the Table Upload chapter.

This chapter describes the first method: creating an empty table by specifying a schema and some metadata in the request body.

Table create requests

An empty table is created by sending a POST request as follows:

POST https://www.googleapis.com/mapsengine/v1/tables
Authorization: Bearer {token}
Content-Type: application/json

{ ...body... }

The request body is JSON.

Required fields

The following fields are required:

  • projectId: The project ID to which the table belongs.
  • name: The table asset name.
  • schema: A schema object containing the schema for this table. A schema object should contain:

    • columns: An array of the table's column information. Each object in the array contains a column name and a type. Allowed types are integer, double, string, mixedGeometry, points, lineStrings, and polygons.
    • Optionally, a primaryKey field. The value of primaryKey must be the name of an existing column in your schema. More information is available from the Primary keys chapter of this guide.

When defining your schema, note that:

  • The first object in the columns array is the primary geometry; it must be named geometry and have a type of points, lineStrings, polygons, or mixedGeometry.
  • No other column can be a geometry type.
  • Column names must be unique within the schema.
  • Column names beginning with gx_ are reserved. Allowed gx_ column names are:

    • gx_location: A column of type string that contains geocodable location strings. Valid only if the geometry column is of type points. The Google Maps Engine service will attempt to geocode the contents of this column and write the location to the geometry column. See the Geocoding chapter for more details.

Optional fields

The following fields are optional:

  • description: The table asset description.
  • draftAccessList: Deprecated. The name of an access list of Map Editor type. The user on whose behalf the request is being sent must be an editor on that access list. A 403 error is returned if these requirements are not met. Note: Google Maps Engine no longer uses access lists. Instead, each asset has its own list of permissions. For backward compatibility, the API still accepts access lists for projects that are already using them. If you created a GME account/project after July 14th, 2014, you will not be able to send API requests that include access lists.
  • publishedAccessList: Deprecated. Defines the access list to whom view permissions are granted. The value must be the name of a Maps Engine access list of the Map Viewer type, and the user must be a viewer on that list. Note: Google Maps Engine no longer uses access lists. Instead, each asset has its own list of permissions. For backward compatibility, the API still accepts access lists for projects that are already using them. If you created a GME account/project after July 14th, 2014, you will not be able to send API requests that include access lists.
  • tags: An array of text strings, with each string representing a tag. More information about tags can be found in the Tagging data article of the Maps Engine help center.

Important notes

Google Maps Engine table limits are documented in the Supported data formats and limits article of the Maps Engine help center. These limits apply to tables created through the API as well as through the web interface. In particular, table create requests should adhere to limits on tag count, tag length, column count, and column name length.

Sample request

A sample table create request is below:

POST https://www.googleapis.com/mapsengine/v1/tables
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": "14182859561222851561",
  "name": "Cascadian Train Stations",
  "description": "A partial list of mag-lev stations in the nation of Cascadia.",
  "tags": [
    "stations", "train", "cascadia"
  ],
  "schema": {
    "columns": [
      {
        "name": "geometry",
        "type": "points"
      },
      {
        "name": "station_name",
        "type": "string"
      }
    ]
  }
}

Table create responses

A successful asset create request returns HTTP code 200 and the JSON-formatted metadata of the created asset. It is similar to the request format with some additional fields:

  • id: The unique ID of the asset.
  • bbox: The bounding box will always be set to encompass the entire globe by default.
  • processingStatus: The processing status of the table. This is always complete.
  • If no primaryKey column is specified in the schema, the service will create an additional column of type string in the schema, gx_id.

Sample response

A sample table create response is below:

{
  "id": "14182859561222851561-10438812281057752385",
  "name": "Cascadian Train Stations",
  "description": "A partial list of mag-lev stations in the nation of Cascadia.",
  "bbox": [-180.0, -90.0, 180.0, 90.0],
  "schema": {
    "columns": [
      {
        "name": "geometry",
        "type": "points"
      },
      {
        "name": "station_name",
        "type": "string"
      },
      {
        "name": "gx_id",
        "type": "string"
      }
    ]
  },
  "processingStatus": "complete",
  "tags": ["stations", "train", "cascadia"]
  ]
}

Known issues

Sending a request to the /tables/{tableId}/features/* endpoint (for example, attempting to add features using batchInsert) immediately after the table's creation may return a 404 Not Found response. If this happens, you can try again within a few seconds.