Skip to main content
The Geoencode API converts address strings into standardized address components and geographic coordinates.

​
Endpoint

POST /api/v1/geoencode
Required role: GEOCODE

​
Request

​
Headers

HeaderRequiredDescription
x-commenda-keyYesYour API key with GEOCODE role
Content-TypeYesMust be application/json

​
Body

{
  "address": "94108, CA, US"
}
FieldTypeRequiredDescription
addressstringYesThe address to geocode (minimum 1 character)

​
Response

​
Success response (200 OK)

{
  "data": {
    "original_address": "94108, CA, US",
    "address_line_1": null,
    "address_line_2": null,
    "city": "San Francisco",
    "state": "California",
    "state_code": "CA",
    "country": "United States",
    "country_code": "US",
    "postal_code": "94108",
    "latitude": 37.7909427,
    "longitude": -122.4084994,
    "provider_request": {
      "address": "94108, CA, US"
    },
    "provider_response": {
      "results": [
        {
          "address_components": [
            {
              "long_name": "94108",
              "short_name": "94108",
              "types": ["postal_code"]
            },
            {
              "long_name": "San Francisco",
              "short_name": "SF",
              "types": ["locality", "political"]
            },
            {
              "long_name": "San Francisco County",
              "short_name": "San Francisco County",
              "types": ["administrative_area_level_2", "political"]
            },
            {
              "long_name": "California",
              "short_name": "CA",
              "types": ["administrative_area_level_1", "political"]
            },
            {
              "long_name": "United States",
              "short_name": "US",
              "types": ["country", "political"]
            }
          ],
          "formatted_address": "San Francisco, CA 94108, USA",
          "geometry": {
            "bounds": {
              "northeast": {
                "lat": 37.7962109,
                "lng": -122.4034656
              },
              "southwest": {
                "lat": 37.785744,
                "lng": -122.4148261
              }
            },
            "location": {
              "lat": 37.7909427,
              "lng": -122.4084994
            },
            "location_type": "APPROXIMATE",
            "viewport": {
              "northeast": {
                "lat": 37.7962109,
                "lng": -122.4034656
              },
              "southwest": {
                "lat": 37.785744,
                "lng": -122.4148261
              }
            }
          },
          "navigation_points": null,
          "partial_match": false,
          "place_id": "ChIJx5rJUYyAhYARxagLGBVGeFs",
          "types": ["postal_code"]
        }
      ],
      "status": "OK"
    },
    "cached_at": 1766029176
  }
}

​
Response fields

FieldTypeDescription
original_addressstringThe address string that was geocoded
address_line_1string | nullPrimary street address
address_line_2string | nullSecondary address information (suite, apt, etc.)
citystring | nullCity name
statestring | nullFull state/province name
state_codestring | nullState/province code (e.g., “CA”)
countrystring | nullFull country name
country_codestring | nullISO country code (e.g., “US”)
postal_codestring | nullPostal/ZIP code
latitudenumber | nullGeographic latitude
longitudenumber | nullGeographic longitude
provider_requestobjectThe request sent to the geocoding provider
provider_responseobjectThe raw response from the geocoding provider (Google)
cached_atnumber | nullUnix timestamp when the result was cached

​
How it works

  1. Check cache: The API first checks if the address has been geocoded before
  2. Cache hit: If found, returns the cached result immediately
  3. Cache miss: If not found, calls Google Geocoding API
  4. Parse response: Extracts address components from Google’s response
  5. Validate state: Checks if the state code is a valid ISO 3166 state code. If not, tries to match it against the subdivision name and then the subdivision local variant to pick the right ISO 3166 state code
  6. Store in cache: Saves the result for future requests
  7. Return response: Returns standardized address data

​
Example requests

​
Basic geocoding

curl -X POST https://address-api.in.commenda.io/api/v1/geoencode \\\n  -H "x-commenda-key: your-api-key" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "address": "1600 Amphitheatre Parkway, Mountain View, CA"\n  }'

​
Postal code lookup

curl -X POST https://address-api.in.commenda.io/api/v1/geoencode \\\n  -H "x-commenda-key: your-api-key" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "address": "94108, CA, US"\n  }'

​
Error responses

​
Invalid request body (400)

{
  "error": {
    "type": "CLIENT_BAD_REQUEST",
    "title": "Invalid request body.",
    "status": 400,
    "instance": "/api/v1/geoencode",
    "detail": {
      "description": "The request body is invalid or missing required fields."
    }
  }
}

​
Missing API key (401)

{
  "error": {
    "type": "CLIENT_UNAUTHORIZED",
    "title": "Missing API key.",
    "status": 401,
    "instance": "/api/v1/geoencode",
    "detail": {
      "description": "The x-commenda-key header is required for authentication."
    }
  }
}

​
Missing role (403)

{
  "error": {
    "type": "CLIENT_FORBIDDEN",
    "title": "Missing required role.",
    "status": 403,
    "instance": "/api/v1/geoencode",
    "detail": {
      "description": "Your API key does not have the GEOCODE role."
    }
  }
}

​
Google API error (500)

If Google’s Geocoding API is unavailable and the address is not in cache: 
{
  "error": {
    "type": "SERVER_INTERNAL_ERROR",
    "title": "Geocoding failed.",
    "status": 500,
    "instance": "/api/v1/geoencode",
    "detail": {
      "description": "Failed to geocode address."
    }
  }
}

​
Caching behavior

The Address API automatically caches geocoding results to improve performance and reduce costs:
  • Cache key: The original address string (case-sensitive)
  • Cache hit: Returns immediately with cached_at timestamp
  • Cache miss: Calls Google API, stores result, returns with cached_at timestamp

​
State code standardization

Google’s Geocoding API may return state information in various formats (ISO code, full name, or local variant). The Address API standardizes these using the ISO 3166 content database:
  1. Google returns ISO code (e.g., “CA”): Validates it’s a valid ISO 3166 code and uses the ISO 3166 code from the database
  2. Google returns full name (e.g., “California”): Matches against subdivision name to find the ISO 3166 code from the database
  3. Google returns local variant (e.g., “Québec”): Matches against subdivision local variant to find the ISO 3166 code from the database
  4. State not found in database: Returns whatever Google provided without failing
This ensures consistent address standardization across all responses while maintaining resilience when encountering unknown subdivisions.