Accessing App Engine with Remote API

The Remote API library allows any Python client to access services available to App Engine applications.

For example, if your App Engine application uses Google Cloud Datastore or Google Cloud Storage, a Python client could access those storage resources using the Remote API.

You can use the Remote API to access your application's data store from an app running on your local machine, or from a local interactive Remote API shell. The Remote API interacts with real services, so this access does use quota and billable resources.

The App Engine SDK for Python includes the Remote API library.

Enabling Remote API access in your app

The easiest way to enable the Remote API for your application is to use the builtins directive in the app.yaml file for your app, which specifies the default URL /_ah/remote_api/. However, you can instead use the url directive in that same file to specify some other URL.


The builtins directive in the app.yaml file makes the Remote API available at the default URL /_ah/remote_api:

runtime: python27
api_version: 1
threadsafe: true

- remote_api: on


Using the url directive in app.yaml lets you specify a different URL for use with the Remote API:

- url: /some-URL/*
  script: google.appengine.ext.remote_api.handler.application

Make sure you deploy your application to App Engine after making this change.

Using the Remote API shell

The Python SDK includes a Remote API shell, which allows you to invoke Python commands on App Engine services used by your application. You don't need to supply any additional authentication, because this automatically uses the same credentials you used to upload the app to App Engine.

To start the Remote API shell:

  1. Invoke the following command from a terminal window on your local machine:


    Replace [GAE-SDK-INSTALL-DIRECTORY] with the path to the App Engine SDK for Python, and [YOUR-PROJECT-ID] with your project ID.

  2. In the interactive shell that is displayed, invoke the Python commands you want to run. For example, if your application uses Cloud Datastore, you could invoke the following ndb query to fetch 10 records:

     >>> from google.appengine.ext import ndb
     >>> # Fetch 10 keys from the datastore
     >>> ndb.Query().fetch(10, keys_only=True)

Using the Remote API in a local client

You can also use the Remote API in local applications to access services used by your app running in App Engine.

To use the Remote API in a local application:

  1. Enable the remote API.

  2. Export the PYTHONPATH environment variable for your Python directory, for example:

     export PYTHONPATH=/usr/somedir/v3/bin/python2.7

    Replace that path with the actual values for your python location.

  3. Add your App Engine SDK for Python location to PYTHONPATH:

     export GAE_SDK_ROOT="/usr/local/home/mydir/google_appengine"

    Replace the SDK path shown above with your actual path to the App Engine SDK.

  4. In your client code, import dev_appserver and call dev_appserver.fix_sys_path() to ensure all of the App Engine SDK modules import correctly:

        import dev_appserver

  5. Add the following remote_api_stub code to your application, making sure you pass it your project ID in your code:


    If don't use the default URL /_ah/remote_api for the Remote API, you'll have to change the code above to reflect the URL you are using. For the definition and documentation for remote_api_stub.ConfigureRemoteApiForOAuth, see the SDK file [GAE-SDK-INSTALL-DIRECTORY]/google/appengine/ext/remote_api/

  6. Add any needed App Engine imports and Python code to access the desired App Engine services. The following sample code accesses the project's data store:

    import argparse
        import dev_appserver
    except ImportError:
        print('Please make sure the App Engine SDK is in your PYTHONPATH.')
    from google.appengine.ext import ndb
    from google.appengine.ext.remote_api import remote_api_stub
    def main(project_id):
        # List the first 10 keys in the datastore.
        keys = ndb.Query().fetch(10, keys_only=True)
        for key in keys:
    if __name__ == '__main__':
        parser = argparse.ArgumentParser(
        parser.add_argument('project_id', help='Your Project ID.')
        args = parser.parse_args()

  7. With your application deployed to App Engine, start your Remote API client:

     python YOUR-PROJECT-ID

    Replacing with your client module, and YOUR-PROJECT-ID with your project ID. This assumes your client accepts project ID as the command-line input, following the code sample.

Send feedback about...