Skip to content

Getting started with the GeoDataHub API

The GeoDataHub Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Web API uses appropriate HTTP verbs for each action.


Looking for our API Reference? Or want to query the API directly from Python.


GeoDataHub uses the secure Oauth 2.0 protocol to authenticate users. All users are provided a time limited access token that uniquely identifies them on the platform.

The fastest way for developers to obtain a valid token is using the command line tool,

gdh login --print-all-tokens

Following the on-screen instructions. If you already logged in use the --use-refresh-token option to print the tokens. The command results in three tokens,

  • Access Token: Used to inform the backend about the users access level
  • Refresh Token: Used to obtain new ID and access tokens
  • Identity Token: Used to identify the user

Copy the tokens and store them in a safe place. The login command automatically stores the token in the users home folder. On Linux/Mac /home/<USERNAME>/.gdh/authentication or on Windows c:\Users\<CurrentUserName>\.gdh\authentication. The authentication file is JSON encoded and contains a single key.


The access and identity tokens expires after 1 hour. Refresh tokens expire after 27 days.

Authenticate against the API by including the access token in the Authorization header parameter.


  "Authorization": "NgCXRK...MzYjw",
curl -X GET -H 'Authorization: eyJ...r9A'
import requests

url = ""
headers = {"Authorization": "Basic ZjM4Zj...Y0MzE="}

resp = requests.get(url, headers=headers)

If successful the command will return a JSON encoded list of all public datasets.

Learn more about the Web API in the basic operations guide.