Hong Kong GeoData Store Authentication: API Key Guide (2026)

Authentication overview

The Hong Kong GeoData Store provides public geospatial data services, including its Geocoding API and Map API. Authentication for these services is designed to be straightforward, primarily relying on the use of API keys. These keys serve as a unique identifier for applications accessing the API, allowing the Hong Kong GeoData Store to manage usage, enforce terms and conditions, and monitor service consumption. Unlike more complex schemes such as OAuth 2.0, API keys offer a simpler integration path, suitable for public data access where user-specific authorization is not the primary concern. The Hong Kong Geocoding API specification details the exact parameters for including these keys in requests.

While API keys simplify access, developers are responsible for their secure management to prevent unauthorized use. All communications with the Hong Kong GeoData Store APIs are expected to occur over HTTPS, encrypting data in transit and protecting the API key from interception. This fundamental security measure is a standard practice across most API providers to ensure the integrity and confidentiality of interactions.

Supported authentication methods

The Hong Kong GeoData Store utilizes a singular, token-based authentication method: the API Key.

API Key

An API Key is a unique string that identifies your application when it makes calls to the Hong Kong GeoData Store APIs. It is passed as a query parameter in your API requests. The purpose of the API key is to track usage, enforce rate limits, and ensure compliance with the service's terms and conditions. The Hong Kong GeoData Store's official documentation outlines how API keys are expected to be used within the URI structure for API calls.

Getting your credentials

To obtain an API key for the Hong Kong GeoData Store APIs, you typically need to register on their official portal. The process generally involves the following steps:

1. Visit the Hong Kong GeoData Store Portal: Navigate to the official Hong Kong GeoData Store homepage.
2. Registration: Look for a 'Register' or 'Sign Up' option. You will likely need to provide an email address and create a password.
3. Account Activation: After registration, you may receive an email to verify your account. Follow the instructions in the email to activate it.
4. API Key Generation: Once logged into your account, there should be a section or dashboard related to API access or developer tools. Here, you can typically generate a new API key. The key will be a long alphanumeric string.
5. Review Terms of Use: Before using the API key, carefully read and understand the Hong Kong GeoData Store's terms of use for their API services. This ensures compliance and proper usage.

Keep your API key confidential. Treat it like a password. If your key is compromised, return to your GeoData Store account portal to revoke the old key and generate a new one.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests. For the Hong Kong GeoData Store Geocoding API, the API key is typically passed as a query parameter named apiKey or similar, as specified in their API documentation.

Here's an example of how to make an authenticated request using the Hong Kong Geocoding API to convert an address to coordinates, using a placeholder API key:

JavaScript (Fetch API)

const API_KEY = 'YOUR_API_KEY_HERE'; // Replace with your actual API key
const ADDRESS_TO_GEOCODE = 'Shop G1, G/F, Peninsula Centre, 67 Mody Road, Tsim Sha Tsui East, Kowloon';

async function geocodeAddress() {
  try {
    const response = await fetch(
      `https://www.geodata.gov.hk/gs/api/v1.0.0/geocode?q=${encodeURIComponent(ADDRESS_TO_GEOCODE)}&apiKey=${API_KEY}`
    );

    if (!response.ok) {
      if (response.status === 401 || response.status === 403) {
        throw new Error('Authentication failed. Check your API key.');
      } else {
        throw new Error(`API request failed with status: ${response.status}`);
      }
    }

    const data = await response.json();
    console.log('Geocoding Result:', data);

  } catch (error) {
    console.error('Error during geocoding:', error.message);
  }
}

geocodeAddress();

In this example, YOUR_API_KEY_HERE should be replaced with the actual API key you generated from the Hong Kong GeoData Store portal. The encodeURIComponent function is used to ensure that the address string is properly formatted for inclusion in a URL, preventing errors with special characters.

Security best practices

Securing your API keys is crucial for protecting your applications and preventing unauthorized access to the Hong Kong GeoData Store's services. Adhering to these best practices helps mitigate common security risks:

• Use HTTPS for all API Calls: Always ensure that all requests to the Hong Kong GeoData Store APIs are made over HTTPS. This encrypts the communication channel, protecting your API key and other data from interception by malicious actors. The use of HTTPS is a fundamental security requirement for any API communication, as highlighted by resources detailing secure contexts in web development.
• Keep API Keys Confidential: Never hardcode API keys directly into public client-side code (e.g., JavaScript in web pages). If your application is client-side, consider using a backend proxy to make API calls, where your API key can be securely stored and managed. For server-side applications, store API keys in environment variables or a secure configuration management system, not directly in your source code repository.
• Restrict API Key Usage: If the Hong Kong GeoData Store portal allows it, configure restrictions on your API key. This might include limiting API key usage to specific IP addresses (your server's IP) or specific HTTP referrers (your domain). This measure ensures that even if a key is exposed, it can only be used from authorized locations or applications.
• Implement Rate Limiting and Monitoring: Monitor your API key usage for any unusual spikes or patterns that might indicate compromise. While the GeoData Store may have its own rate limits, implementing client-side rate limiting can help prevent excessive billing or service disruptions in case of unauthorized access.
• Rotate API Keys Regularly: Periodically rotate your API keys. This practice minimizes the window of opportunity for a compromised key to be exploited. If you suspect a key has been compromised, revoke it immediately through your GeoData Store account and generate a new one.
• Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. This should include logging errors for review without exposing sensitive information to end-users.
• Avoid Storing Keys in Version Control: Never commit API keys or files containing them to version control systems like Git. Use .gitignore files to exclude configuration files that contain sensitive credentials.

By following these security guidelines, developers can significantly reduce the risk of API key compromise and ensure the secure and compliant use of the Hong Kong GeoData Store's geospatial services.