A command-line interface for Google Maps Engine.

Requires Python 2.7 (32bit).

Note: If you receive a "setuptools pip failed with error code 1" error whilst setting up your virtualenv you need to downgrade to virtualenv 1.11.2 due to this issue.

pip install virtualenv==1.11.2

virtualenv venv
. venv/bin/activate
pip install --editable .

If you don't already have Python installed check out ActivePython.

virtualenv venv
venv\Scripts\activate.bat
pip install --editable .

Note: If you receive the error "error: Unable to find vcvarsall.bat" whilst Hodor is installing you need to install a C compiler due to this issue. Simply download Visual Studio C++ 2008 Express Edition, open another command prompt, and away you go.

The first time you run Hodor he will open a browser window and prompt you to authorise him to access Google Maps Engine on your behalf. When the The authentication flow has completed message shows you can close the tab and return to your terminal.

Hodor ships with its own application credentials, so by default you don't need to setup anything else.

However, Hodor's application credentials are limited to 10,000 requests/day, so it is possible for other users of Hodor to exhaust this shared pool.

If you find this occurring (a) let me know, and (b) you can setup your own applications credentials thusly:

1. Go to the Google Developers Console and Create a new project
2. Go to the APIs & Auth section and enable the Google Maps Engine API
3. Click on Credentials and create a new Installed Application
4. Create oauth.json in the directory you have Hodor installed in and include your new clientId and Secret.
5. Remove the existing credentials-store.json file.

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Hodor knows about:

• Uploading and creating raster and vector assets, and adding them to layers and raster collections.
• Bulk ingest of raster assets.
• Querying vector tables.
• Modifying the contents of vector tables (WIP).

To work out what capabilities a certain Hodor command has simply pass --help on the end of the command.

To begin using Hodor, first activate your virtual environment:

Linux

. venv/bin/activate

Windows

venv/Scripts/activate.bat

Hodor can upload raster and vector data to create new assets and, optionally, directly create new layers or append to an existing raster collection or layer.

Upload a new raster image:

hodor create raster "test-data/Alkimos 1963/config.json"

Upload a new vector table and create a layer from it:

hodor create vector --layer-configfile=test-data/daa_003_subet/layers.json "test-data/daa_003_subet/config.json"

Upload a new raster image and add it to an existing raster mosaic:

hodor create raster --mosaic-id={asset-id} "test-data/Alkimos 1963/config.json"

Recommended directory structure:

agency-name/        -- Name of the custodian agency (e.g. Landgate)
  asset-name/       -- Name of the dataset (e.g. lgate_cadastre_poly_1)
    config.json     -- Store your asset metadata here
    payload/        -- Store your data here (e.g. Shapefiles, JPEG2000)

Hodor supports bulk ingest of raster assets based on a single JSON confguration file.

hodor bulk-load raster "test-data/raster_birds/config.json"

In this mode Hodor will create one new raster asset for every file in your payload directory. Each asset will be based on the template information provided in config.json, with the name the asset being set to the name of the file.

config.json should contain your asset metadata fields in JSON format as defined by Google Maps Engine.

See the GME API documentation for the minimum required fields for vector and raster data.

{
  "projectId": "{your-gme-project-id}",
  "name": "Alkimos 1964 Hodor Test",
  "draftAccessList": "Map Editors",
  "attribution": "Landgate",
  "rasterType": "image",
  "description":"This is a description.",
  "tags" : ["hodor"],
  "maskType":"imageMask",
  "acquisitionTime": {
    "start" : "2010-01-24T00:00:00Z",
    "end" : "2010-01-25T00:00:00Z",
    "precision" : "day"
  }
}

layers.json should contain your layer metadata fields in JSON format as defined by Google Maps Engine.

See the layer create documentation for the minium required fields.

{
  "projectId": "06151154151057343427",
  "layers": [
    {
      "name": "daa_003_subset layer",
      "datasourceType": "table",
      "draftAccessList": "Map Editors",
      "tags": ["Hodor"],
      "styleFile": "style.json",
      "infoWindowFile": "infoWindow.html"
    }
  ]
}

layers.json supports two optional fields:

styleFile is an optional parameter that will use the given file as the layer's style document.

infoWindowFile is an optional parameter that will read the given HTML file into the layer's style document.

Hodor can query vector tables and export the results to the GeoJSON format, including:

• Limiting the query to a specific bounding box and GME's SQL-like query language.
• Querying huge areas by splitting the bounding box into manageable chunks.
• Multi-threaded querying to send many requests to GME in parallel for optimised retrieval.

Return all of the features from a vector table:

hodor features list {table-id} features.json

Return all of the features from a vector table in a given area and with a LOCALITY of NANNUP:

hodor features list -bbox="115.876581, -31.926812, 115.960266, -31.893442" -where="LOCALITY <> 'NANNUP'" {table-id} features.json

Some associated documentation for anyone wishing to build on or understand this wee tool.

Installing the Google Maps Engine API Client Library for Python

The PyDoc reference for the Google Maps Engine API

APIs Explorer for the Google Maps Engine API

Google API Discovery Service for GME

Due credit and thanks go to the folks that put together the Google Cloud Platform code samples, particularly the chunked transfer example on which Hodor was originally based.

And to Armin Ronacher for his fantastic Click library.