The Google Fusion Tables API v1 has been deprecated as of May 3rd, 2016. The API will continue to work until August 1st, 2017, and will shut down on that date. A migration guide is available outlining the steps to take to migrate to v2.

Introduction

This document is intended for developers who want to write applications
that can interact with the Fusion Tables API using REST.
Google Fusion Tables is data management web application
in the cloud for storing and visualizing your data.

If you're unfamiliar with Google Fusion Tables concepts, you should read
Getting Started before starting to code.

Identifying your application and authorizing requests

Every request your application sends to the Fusion Tables API needs to identify your application to Google. There are two ways to identify your application: using an OAuth 2.0 token (which also authorizes the request) and/or using the application's API key. Here's how to determine which of those options to use:

If the request requires authorization (such as a request for an individual's private data), then the application must provide an OAuth 2.0 token with the request. The application may also provide the API key, but it doesn't have to.

If the request doesn't require authorization (such as a request for public data), then the application must provide either the API key or an OAuth 2.0 token, or both—whatever option is most convenient for you.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Google Sign-In, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

Requests to the Fusion Tables API for non-public user data must be authorized by an authenticated user.

If Google determines that your request and the token are valid, it returns the requested data.

Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.

Here's the OAuth 2.0 scope information for the Fusion Tables API:

Scope

Meaning

https://www.googleapis.com/auth/fusiontables

Read/write access.

https://www.googleapis.com/auth/fusiontables.readonly

Read-only access.

To request access using OAuth 2.0, your application needs the scope information, as well as
information that Google supplies when you register your application (such as the client ID and the
client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Acquiring and using an API key

Requests to the Fusion Tables API for public data must be accompanied by an identifier, which can
be an API key or an
access token.

Table access permissions

The default settings for a new table is to be private and exportable.
Owners and editors can control access to a table in these ways:

Private.
Only the owner and editors have access to your table. Visualizations
embedded in other websites and Google Earth network links cannot
authenticate to Fusion Tables when they call for data, so the table
must be Public or Unlisted for these features to work.
To change: In the
Docs List API, change ACLs to allow "default" type,
which makes the table publicly shared with all users. In the web
application, click the Share button and select Public in the
Sharing settings dialog box.

Public.
No authentication required for read-only HTTP GET access,
provided the table is exportable.
To change: In the
Docs List API, change ACLs to limit access by user role or type.
In the web application, click the Share button and select Private
in the Sharing settings dialog box.

Unlisted.
No authentication required for read-only HTTP GET access,
provided the table is exportable.
Embedded visualizations and Google Earth network links have access,
but your table is not included in Fusion Tables public search and
it is not suggested to search engines for indexing although
they may discover the URL through links you create online.
To change: in the web application, click the Share button and
deselect the "Anyone with the link" radio button in
the Sharing settings dialog box to make the table completely
private or completely public. You cannot make this change
in the API.

Exportable.
Anyone can download the table data and authentication is not
required for read-only HTTP GET access.
To change:
In the Fusion Tables API, change the table property to be
"isExportable = false." In the web
application, choose Edit > Modify Table Info and deselect
"exportable" checkbox. A table that is public or unlisted but
that is not exportable
allows read-only access but does not allow data downloading.

Working with tables

Fusion Tables offers a way to easily create, modify, and visualize tables
of data. You can
import data in .csv or .kml and other file formats or create a table from scratch.
In Fusion Tables, data is contained in a
table resource that has various columns of data.
You can use the API to manage the data columns and to customize the info
windows and styles that are used when visualizing the data.
A table resource specifies the columns and attributes associated with the
table. All tables have a unique tableId that you use to
manage the table and its columns, templates, and styles.

Retrieving a list of tables

Listing tables is useful because it provides the table ID and column names of tables that are
necessary for other calls. You can retrieve the list of tables a user owns
by sending an HTTP GET request to the URI with the following format:

https://www.googleapis.com/fusiontables/v1/tables

This list request does not include public tables or tables that
have been shared with the user at any access level. By default, twenty-five results
are returned.
Use the maxResults parameter to change the number of results returned.
Use the pageToken parameters to return additional pages of results.

Request

Here is an example of requesting all tables an authenticated user owns:

GET https://www.googleapis.com/fusiontables/v1/tables

Let's say the user owns two tables: The first table has two columns and the
second table has three columns. Each column is defined by its name and type.
Each table also has a description parameter that further describes the
contents of the table. The isExportable parameter is a boolean value
that is set to true by default. You can set it to false to prevent others from
exporting the table or accessing it through the API.

Response

If the request succeeds, the server responds with the 200 OK
HTTP status code and the list of tables:

Response

If the request succeeds, the server responds with the 200 OK
HTTP status code and the definition of the copied table. This request created a new
table with table with tableId
ai378sk_jeidlckswe_ccccccccc_29d9Ika.

Response

If the request succeeds, the server responds with the 200 OK
HTTP status code and the number of rows it received. Once the response is returned,
the rows will be imported asynchronously in the background.

200 OK
{
"kind": "fusiontables#import",
"numRowsReceived": "2"
}

Working with columns

Fusion Tables also offers a way to
modify columns for a given Fusion Table. A column resource specifies the
different attributes associated with a column
in a table: ID, name, and type.
Column types can be "STRING", "NUMBER", "DATETIME", or
"LOCATION".

Note: You cannot use the API to
programmatically modify columns that are
two-column locations, but you can use the Fusion Tables web
application to modify this once the table has been created.

Parsing of the column ID

The column ID is a string value. If the ID can be parsed as an integer,
Fusion Tables assumes the value is a column ID and retrieves the column
with that ID. If it cannot be parsed as an integer, it is assumed to
be a name and Fusion Tables retrieves the column with that name. If
there are multiple columns with the same name, the one with the
lowest column ID is retrieved.

If a column has a name that is an integer, you can only access it
through the ID and not through its name. For example, if you have a table
with these two columns:

First column: ID 0, name "1"

Second column: ID 1, name "foo"

If you try to get the column with column ID=1, you'll get the
second column, not the first. To get the first, you must
use column ID=0.

Retrieving a list of columns

You can retrieve a list of columns for a table, given its
table ID, by sending an HTTP
GET request to the URI with the following format:

https://www.googleapis.com/fusiontables/v1/tables/tableId/columns

The list request returns up to 50 results by default.
Use the maxResults parameter to change the
number of results returned.
Use the pageToken parameter to page through
results.

Response

If the request succeeds, the server responds with the 200 OK HTTP
status code and the new table data created. This request created a new column in
table 1e7y6mtqv891111111111_aaaaaaaaa_CvWhg9gc with columnId 3.

Updating a column

Retrieve the resource that you want to update. This can be done by making a GET
request for a specific column in a table, given its
table ID. See Retrieving a
column.

Modify the properties you want to change. Properties that can be modified include the
name and type of the column. You cannot use the Fusion Tables API to change a
column's type in views and merged tables.

Send a PUT request to the resource URI and supply the modified resource as the
message body.

Note: You cannot use the Fusion Tables API
to create or update columns with
type "LOCATION" that have a latitude in one column and a
longitude in another and are designated as a
"
two column location".
Requests to modify the "type" of any such column
will return a 400 Bad Request error.

Request

Here is an example of updating column 1 in table 1e7y6mtqv891111111111_aaaaaaaaa_CvWhg9gc,
which changes the column "name" from "Size of Group" to "Dominant Markings"
and changes the "type"
from "NUMBER" to "STRING".

Response

If the request succeeds, the server responds with a 204 No Content status code.

Working with Templates

You can use the Google Fusion Tables API v1.0 to customize the info-window template in
a similar way to the Fusion Tables web application. See
Customize info windows.

By default, a table has one default template for displaying a map
visualization within the Fusion Tables web application. The template may
use the set of automatic columns from the table or it may contain
custom HTML code. In either case, you can use the Fusion Tables API
to change the default template for a table and
to create and update other templates. Updates to a table's default
template are reflected in the web application.
Maps embedded elsewhere using the Google Maps API can specify
different templates.

Templates can be created using a list of automatic columns or by
using custom HTML with inline CSS. When defining the custom HTML,
use curly brackets around the column name to pull the data from that
column and row into the template.

There are several code samples
that customize info window templates. You may find it helpful to step
through their code.

Retrieving a list of templates

You can retrieve a list of templates for a table, given its
table ID, by sending an
HTTP GET request to the URI with the following format:

Response

If the request succeeds, the server responds with a
204 No Content status code.

Working with styles

Fusion Tables offers different ways to style map features for a given
table. Map features can be points, lines, and polygons. See
Working with geographic data for the types of location information
supported in LOCATION columns. You can customize the appearance of
features on the map by setting styles in the application or
programmatically. You can customize the appearance of features
on the map by setting styles in
Fusion Tables web application or programmatically.

There are several code
samples that customize map styles. You may find it helpful to step
through their code.

There are different ways to visualize data on a map:

By using the Fusion Tables web application

By copying the "Get embeddable code" and pasting an iframe
with the map visualization into another website

By using the Google Maps API's
Fusion Tables Layer with Javascript to integrate the map
into a web page

Stored styles

By default, a table has one style for displaying a map
visualization within the Fusion Tables web application. You can use
the Google Fusion Tables API v1.0 to change this default for a table and
to create and update other styles. A single table can have multiple
Style Resources
and you can define one of them as a default style for a table by
setting the "isDefaultForTable" parameter for
that Style Resource.

A stored style is a Style Resource created and managed by the
Fusion Tables API. To select a stored style to use for styling
the features on the map, set the "styleId" property in the
Fusion Tables Layer object to its ID. The Google Maps API supports up
to five Fusion Tables Layers in one map, and each may specify its
own styleId. The
sample code page has a useful
example
of its usage. Syntax is as follows:

A map within the Fusion Tables web application or an embedded
iframe uses the default stored style for the table.
You can use Fusion Tables API 1.0 to edit this default stored
style and create new styles.

Dynamic styles

Dynamic style rules, specified using the "styles" property
in the
Maps API, override the default style or styleId for
a layer.

Note: Since dynamic styles are
not stored and not available through the Fusion Tables API, all
styles mentioned in this document refer to stored styles.

Choosing a style

Maps created using the Google Maps API's Fusion Tables Layer
can be styled in several ways:

Using the default stored style for the table, as above.

Applying a different stored style using the "styleId" parameter
in the FusionTablesLayer's Javascript

Specifying dynamic styling using the "styles" parameter in the
FusionTablesLayer object. These styles are not stored with the table
and are suited to dynamically changing the map display in response
to users' interactions with the webpage.

Request

Here is an example requesting all styles from table 1e7y6mtqv893333333333_ccccccccc_CvWhg9gc:

GET https://www.googleapis.com/fusiontables/v1/tables/1e7y6mtqv893333333333_ccccccccc_CvWhg9gc/styles

The table has two styles. The first defines a marker option setting all the
markers to "small_red" and a polyline option that sets a gradient
with a range of 1 to 100 on the values
in the column named population and also sets a stroke weight of 2px.
The second style sets the fill color of all polygons to #0000FF with
an opacity of 0.2, meaning 20% opaque.

Response

If the request succeeds, the server responds with the
200 OK HTTP status code and the list of styles for the
table:

Response

If the request succeeds, the server responds with a
204 No Content status code.

Working with rows

The Google Fusion Tables API v1.0 uses SQL statements to work with rows. Fusion
Tables SQL statements are sent to the Google Fusion Tables server
using HTTP GET requests (for queries) and POST
requests (for inserts, updates, and deletes) from a client application.

You can use SQL statements to construct complex queries to identify
rows that match specific criteria. The
Querying for data section
describes how to set filtering criteria and how to define grouping or
sorting of the results.

Retrieving a row ID or a list of row IDs

To update or delete a particular row, you need the row's ID. This is an
internally generated number that uniquely identifies each row as it is inserted
or uploaded into a Fusion Tables table. By default, data is returned
in JSON format. You can obtain CSV format by using the
alt=csv query parameter in your SQL statement.

In v2, you can download larger result sets by specifying
alt=media. It will respond with the CSV data in the response
body.

Response

If the SELECT statement is successful, f the request succeeds, the server responds with the 200 OK HTTP status code and
the requested results in typed JSON format. You can also obtain untyped JSON or CSV formatted data with a query parameter.

Considerations

You must have the row ID.
You can get this from a previous SELECT or INSERT statement.

You must know the names of the columns you want to update.
To find out what columns are available
in a given table, use the
Google Fusion Tables API v1.0 to retrieve
a list of all columns in a table.

If more than one row matches the selection criteria, multiple rows
are returned and you will need to make your SELECT query more specific
to identify the particular row you want to update.

Note: You can only update rows in the table
if authenticated as an owner or editor on the table. The user must
be authenticated to create Google Fusion Tables resources, so you must
provide the Authorization HTTP header with the
POST request.

Usage restrictions

When you update a row in a base table, any views or merged
tables that are derived from that base table will also acquire the new data.

In a merged table, you cannot update the value in
the key column. If you want to update a key value, do so in
the base table from which the merged table was derived.
The change will be reflected in the merged table.

Request

To adjust inventory levels after the sale of one pair of red shoes,
run a query to find the row that contains Red Shoe:

Considerations

You must have the row ID.
You can get this from a previous SELECT or INSERT statement.

When you delete a row or rows from a base table, the change
is reflected in views and merged tables that are derived
from that base table. The reflection looks like this:

In a view, the row or rows are removed.

In a merged table where the base table was the first
one present
— that is, the table selected in
the Google Fusion Tables website
before the Merge button was clicked —
the row or rows are removed entirely. (For those familiar with SQL:
the base table was the driving table in the join.)

In a merged table where the base table was not the
first one present, the row or rows are not removed from the merged
table. What is removed? The values in the row or rows that were drawn from the
base table where the row or rows were deleted.
(For those familiar with SQL: the base table was a
lookup table in the join.)

If maxResults=10, at most 10 results will be returned in a
list request.

The default varies depending on the type of resource.

Only GET operations for list requests.

pageToken

Returns the next page of results.

No pageToken is required for the first page of results.

The pageToken can be found in the body of the response under
"nextPageToken".

If there are no more pages of results to display, the response will not return a
next token.

Only GET operations for list requests.

prettyPrint

Returns a response with indentations and line breaks

If prettyPrint=true, the results returned by the
server will be human readable (pretty printed).

Default: prettyPrint=false

All operations for all resources

Working with geographic data

Fusion Tables makes it simple to map a database of locations and
run spatial queries on it (See the
Fusion Tables Reference). To display the results of your query on a
Google map, you can use the UI (view the Create a map tutorial in the
Classic
and the New look
versions of the web application tutorial)
or you can use the API with the
FusionTablesLayer Maps API v3.0 object. If you're not
familiar with Fusion Tables Layers, you can find more
information in this
blog post.

Note: If you're using the Fusion
Tables Layer object in the Google Maps API to display data on a map, your
map is subject to the limits announced in this
blog post.

Geographic design constraints

It's useful to keep in mind these limits:

Only the first 350,000 rows of data in a table are mapped
or included in spatial query results.*Therefore:

Maps made with Fusion Tables Layers in the Google Maps API or
with the Fusion Tables web application will only show data
from within this first 350,000 rows. If you apply a filter to a
table larger than 350K rows and the filter matches data in rows
after the first 350K, these rows will not appear on the map.

Queries with spatial predicates only return data from within this
first 350K rows. If you apply a SELECT query with a
spatial predicate to a very large table
and the query matches data in rows after the first 350K,
these rows are not returned.

When importing or inserting data, remember:

The total size of the data sent in one API call cannot exceed 1MB.

API calls to write data should not exceed 0.5 qps per table.

A cell of data in Fusion Tables supports a maximum of 1 million characters;
it may sometimes be necessary to reduce the precision of
coordinates or simplify polygon or line descriptions.

The maximum number of vertices supported per table is 5 million.*

When looking at the map, you may notice:

The ten largest-area components of a multi-geometry are shown.

When zoomed far out, map tiles may exceed the 500 feature-per-tile
limit, and features will be dropped from the map.*

When zoomed farther out, tables with more than 500 features will
replace lines or polygons with dots.*

Geographic locations

A geographic location is a string that contains
any of the following:

A street address,
name of a city,
name of a country, or any location description understood by Google Maps.
If your source repository stores address information
in several columns, merge them
into a single column before uploading the data
to Google Fusion Tables.

Latitude, longitude pair. Use decimal degrees.
Separate the numbers with a space or comma.

Note: Like all other Google mapping tools,
Google Fusion Tables assumes the WGS 84 datum.
If your location data is in a different datum,
convert it first for the most accurate mapping.

To add geographic location in a table using the API:

Make a column of type LOCATION.
This can be done
in a CREATE TABLE statement.

Use an INSERT or UPDATE statement to
fill the column with a string.

You can also import data through the Google Fusion Tables website:

Click "New table" and import your data.

When your table is imported, check that the
geographic information column was correctly detected
as type LOCATION. From the Edit menu, select "Modify columns".
The column's type is shown to the right of the name.

If the type is not Location, click the column name
and change the type, then click Save.

Geocoding location descriptions

Geographic data that is a description of a location
must be geocoded in order to place it on a map.
Latitude, longitude pairs and KML are already mappable.

To geocode your location descriptions stored in a table,
go to the Google Fusion Tables website and choose
the Map visualization, or select "Geocode" from the File menu.
There is a limited number of geocodes offered for
free per user per day, so very large data sets may require
repeating this step until the file is entirely geocoded.

If a description geocodes to the wrong location, please see
Fix map marker locations.
To determine if geocoding any locations failed, use the
"highlight untyped values" format for the location column
and visually scan the data for descriptions shown
with a yellow highlight.

Using KML data

You can store the geographic coordinates of
points, lines, and polygons in a table
by using KML.
Use an INSERT or UPDATE statement to place a KML string
in any column where the type has been set to LOCATION.
This is useful to associate
data with locations so that the data can be
visualized on a map.

When using KML syntax, be sure to avoid these
common pitfalls:

Do not put a space character after a comma
when specifying latitude and longitude.
For example, 10,10 is correct, but
10, 10 is not.

Use upper- or lowercase exactly as shown in the syntax.
For example, <Point> is correct, but
<point> is not.

Remember that the longitude comes first in
KML long/lat pairs—just the opposite
of the order used when specifying a lat/long pair
as an ordinary string.

Syntax

To store KML in a table,
include the KML in the <value> argument of an INSERT or UPDATE statement
using one of the following syntactic choices.

Examples

Suppose you have a table with a
table ID of 1e7y6mtqv892222222222_bbbbbbbbb_CvWhg9gc, a
STRING column called CityDescription,
and a LOCATION column called CityLocation.
You can store the location in several ways. To store the
location of Tokyo as an ordinary search string:

To map a plot of land for surveying wildlife populations in the
Desert Tortoise Natural Area in the Mojave Desert, California
(assuming a research volunteer database with ID 1e7y6mtqv893333333333_ccccccccc_CvWhg9gc),
use KML to outline the area:

Reserved words

Fusion Tables has the following reserved words. We recommend you not use
them as table, view, or column names. If, however, you need to for some reason, make
sure you enclose them in single quotes.

AND
ASC
AS
BY
CASE
CIRCLE
CONTAINS
CONTAIN
CREATE
DELETE
DESCRIBE
DESC
DOES
DROP
ENDS
EQUAL
FROM
GROUP
IGNORING
IN
INSERT
INTO
LATLNG
LIKE
LIMIT
MATCHES
NEAR
NOT
OFFSET
ORDER
POLYGON
RECTANGLE
ROWID
SELECT
SET
SHOW
SKIP
ST_DISTANCE
ST_INTERSECTS
STARTS
TABLES
TABLE
TO
UPDATE
VALUES
VIEW
WHERE
WITH
ID
NUMBER
DOCID
STRING