Skip to main content

Authentication

All API requests require authentication via an API key. There are two ways to pass your key.

Authentication Methods​

Pass your API key in the X-Api-Key HTTP header:

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=Paris"

Query Parameter Authentication​

Pass your API key as the api_key query parameter:

curl "https://api.geocodeme.net/v1/geocode?q=Paris&api_key=gm_YOUR_API_KEY"
Security Note

API keys passed as query parameters can leak through server access logs, browser history, Referer headers, and proxy logs. Always prefer header authentication for production applications. Only use query parameter authentication for quick testing or environments where headers cannot be set.

info

The X-Api-Key header takes priority if both methods are provided in the same request.

API Key Format​

API keys follow this format:

  • Prefix: gm_
  • Total length: 35 characters (gm_ + 32 URL-safe characters: letters, digits, - and _)
  • Example: gm_EXAMPLE00KEY00ONLY00aaabbbcccddd
warning

API keys are displayed only once at creation. Store your key in an environment variable (e.g. GEOCODEME_API_KEY) and never commit it to version control.

Getting an API Key​

  1. Sign in to your account at geocodeme.net
  2. Navigate to Dashboard > API Keys
  3. Click Create Key
  4. Copy the key immediately; it will not be shown again

Key Rotation​

To rotate an API key:

  1. Go to Dashboard > API Keys
  2. Click Revoke on the key you want to replace
  3. Click Create Key to generate a new one
  4. Update your application with the new key

The old key becomes invalid immediately upon revocation. Plan for a brief service interruption during rotation, or create the new key before revoking the old one.