Google Geocoding

The Google Geocoding business function provides address verification and normalization services using Google's Geocoding API. This function allows you to validate addresses, extract structured address

Settings Configuration

Before using the Google Geocoding function, you need to configure your workspace settings:

Setting	Description	Required	Default
Google Maps API Key	Your Google Maps Platform API key with Geocoding API enabled	Yes	-

Configuration Steps

1. Go to Workspace Settings > Business Integrations

2. Locate the Google Maps section

3. Enter your Google Maps API Key

4. Save the settings

Getting a Google Maps API Key

1. Visit the Google Cloud Console

2. Create a new project or select an existing one

3. Enable the Geocoding API

4. Create credentials (API Key)

5. Configure API key restrictions (recommended for security)

6. Copy the API key to your workspace settings

Function Parameters

All parameters are optional - provide the address information you have available:

Parameter	Type	Description	Example
street	string	Street name and house number	"Hauptstrasse 123"
city	string	City or locality name	"Berlin"
postalCode	string	Postal or ZIP code	"10115"
country	string	Country name or ISO code	"Deutschland" or "DE"

Response Format

Successful Response

{
  "success": true,
  "found": true,
  "formattedAddress": "Hauptstrasse 123, 10115 Berlin, Deutschland",
  "normalized": {
    "street": "Hauptstrasse 123",
    "postalCode": "10115",
    "city": "Berlin",
    "state": "Berlin",
    "country": "Deutschland",
    "countryCode": "DE"
  },
  "validation": {
    "confidence": "high",
    "isComplete": true
  }
}

Address Not Found

{
  "success": true,
  "found": false,
  "errorMessage": "No address found for the provided information"
}

Configuration Error

{
  "success": false,
  "found": false,
  "errorMessage": "Google Maps API key not configured"
}

Confidence Levels

The validation confidence indicates how accurate the geocoding result is:

• high: Exact address match (rooftop level accuracy)

• medium: Street-level or interpolated accuracy

• low: Approximate or area-level accuracy

Usage Examples

Example 1: Complete Address Verification

// Verify a complete address
const response = app.businessFunction({
    functionName: "GoogleGeocoding",
    methodName: "Geocode",
    street: "Hauptstrasse 123",
    city: "Berlin",
    postalCode: "10115",
    country: "DE"
});

if (response.success && response.found) {
    console.log("Verified address:", response.formattedAddress);
    
    // Use normalized components to update form fields
    app.setFieldValue("street", response.normalized.street);
    app.setFieldValue("city", response.normalized.city);
    app.setFieldValue("postalCode", response.normalized.postalCode);
    app.setFieldValue("country", response.normalized.country);
    
    // Check confidence level
    if (response.validation.confidence === "high") {
        console.log("Address verified with high confidence");
        app.setFieldColor("addressSection", "green");
    }
} else {
    console.log("Address verification failed:", response.errorMessage);
    app.setFieldColor("addressSection", "red");
}

Example 2: Partial Address Lookup

// Verify with minimal information
const response = app.businessFunction({
    functionName: "GoogleGeocoding",
    methodName: "Geocode",
    city: "München",
    postalCode: "80331"
});

Example 3: Address Validation in Form

const response = app.businessFunction({
    functionName: "GoogleGeocoding",
    methodName: "Geocode",
    street: app.getFieldValue("street"),
    city: app.getFieldValue("city"),
    postalCode: app.getFieldValue("postalCode"),
    country: app.getFieldValue("country")
});

if (response.success && response.found) {
    // Show validation success
    app.showMessage("Address verified successfully", "success");
    
    // Optionally update fields with normalized data
    if (response.normalized.city !== app.getFieldValue("city")) {
        app.setFieldValue("city", response.normalized.city);
        app.showMessage("City name corrected", "info");
    }
    
    // Store validation info for later use
    app.setFieldValue("addressConfidence", response.validation.confidence);
    app.setFieldValue("addressComplete", response.validation.isComplete);
    
} else if (response.success && !response.found) {
    app.showMessage("Address could not be verified. Please check your input.", "warning");
} else {
    app.showMessage("Address validation failed: " + response.errorMessage, "error");
}

Error Handling

Always implement proper error handling for address validation:

const response = app.businessFunction({
    functionName: "GoogleGeocoding",
    methodName: "Geocode",
    street: addressData.street,
    city: addressData.city,
    postalCode: addressData.postalCode,
    country: addressData.country
});

if (!response.success) {
    // Configuration or system error
    console.error("Geocoding service error:", response.errorMessage);
    return { valid: false, error: "Service unavailable" };
}

if (!response.found) {
    // Address not found
    return { valid: false, error: "Address not found" };
}

// Success, handle the response