Skip to main content

External API Integration - Google Maps Places

Description​

This query demonstrates Stack9's capability to integrate with external third-party APIs, showcasing how the framework can act as a proxy and orchestration layer for external services. The query uses a custom connector (google_maps_places_api) to call Google's Places Autocomplete API, demonstrating how Stack9 can unify internal and external data sources under a consistent query interface. This pattern allows applications to leverage external services while maintaining a single, unified query mechanism.

The query structure shows how external API parameters are mapped and encoded, with the API key being injected as a parameter for security and the search term being dynamically provided. The URL encoding in the path (%2C for commas, %3A for colons) demonstrates proper handling of special characters in query strings. The components=country:AU parameter shows how queries can be pre-configured with regional constraints, ensuring that autocomplete results are relevant to the application's geographic scope.

This integration pattern is crucial for modern applications that need to combine internal business data with external services like mapping, payment processing, or third-party data providers. By wrapping external APIs in Stack9's query system, applications gain benefits like consistent error handling, logging, caching, and the ability to swap providers without changing application code. The connector abstraction also allows for API key management, rate limiting, and retry logic to be handled at the framework level.

Use Case​

Used in address entry forms throughout the CRM system to provide real-time address suggestions as users type, improving data quality and user experience by leveraging Google's comprehensive address database for Australian addresses.

Key Features​

  • Integration with external Google Maps Places API
  • Custom connector configuration for third-party services
  • URL parameter encoding for special characters
  • Dynamic parameter injection for search terms and API keys
  • Geographic filtering through components parameter
  • Standardized query interface for both internal and external APIs

Query Type​

SELECT

JSON Definition​

{
  "key": "addressfinderautocomplete",
  "name": "addressFinderAutoComplete",
  "connector": "google_maps_places_api",
  "queryTemplate": {
    "method": "get",
    "path": "/autocomplete/json?key={{key}}&fields=place_id%2Cformatted_address&inputtype=textquery&input={{searchTerm}}&components=country:AU"
  },
  "userParams": {
    "key": "",
    "searchTerm": "10 edinglassie"
  }
}

Notes​

  • The API key should be stored securely and injected at runtime, never hardcoded in the query definition
  • The fields parameter limits the response to specific data points, reducing API costs and response size
  • URL encoding is crucial for special characters - use %2C for commas, %20 or + for spaces
  • The components filter restricts results to Australia (AU), which should be configurable for multi-region deployments
  • This pattern can be extended to other Google APIs (Geocoding, Distance Matrix) or other providers (HERE, Mapbox)
  • Consider implementing caching for common searches to reduce API calls and improve response times
  • Rate limiting should be implemented at the connector level to avoid exceeding API quotas
  • The example search term "10 edinglassie" in userParams is for testing/documentation purposes only