Geographic Data API (GoogleMap)

The GoogleMap integration provides comprehensive geographic data lookup services for countries, states, cities, and postal codes. Despite the name, this is not a Google Maps API integration but rather a local geographic database service that enables location-based search and address validation.

Service Type

This is a local data service that uses pre-loaded geographic databases (194 JS files), not an external API integration. No API keys or external service calls are required.

Architecture Overview

graph TB
    subgraph "Client Layer"
        A[Frontend Application]
    end

    subgraph "DashClicks External API"
        B[GoogleMap Router]
        C[Search Controllers]
        D[Geographic Data Files]
    end

    subgraph "Data Assets"
        E[Country Data JSON<br/>~200 countries]
        F[State Data JSON<br/>~5000 states]
        G[City Data JSON<br/>~150k cities]
        H[Postal Code Assets<br/>90+ country files]
    end

    A -->|Search Requests| B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    C -->|Filtered Results| A

    style D fill:#9cf,stroke:#333,stroke-width:2px
    style H fill:#fcf,stroke:#333,stroke-width:2px

Key Features

Geographic Search

• Country Lookup: Search and retrieve country information with metadata
• State/Province Search: Find states/provinces by country or search text
• City Search: Search cities with state and country context
• Postal Code Lookup: Find postal codes by location hierarchy
• Hierarchical Data: Linked country → state → city → postal code relationships

Data Coverage

• Countries: ~200 countries with ISO codes, phone codes, currencies
• States: ~5,000 states/provinces/regions worldwide
• Cities: ~150,000 cities globally
• Postal Codes: 90+ countries with ZIP/postal code data

Integration Components

File Structure

external/Integrations/GoogleMap/
├── index.js                          # Main router
├── README.md                         # API documentation
├── docs.json                         # API endpoint docs
├── data/
│   ├── countries+states+cities.json  # Complete geographic dataset
│   ├── countries.json                # Country master data
│   ├── states.json                   # State/province data
│   └── cities.json                   # City data
├── assets/                           # Country-specific postal code files
│   ├── US/                           # United States ZIP codes
│   ├── CA/                           # Canada postal codes
│   ├── GB/                           # UK postal codes
│   ├── AU/                           # Australia postal codes
│   └── [85+ more countries]
├── src/
│   ├── index.js                      # Z1P library wrapper
│   ├── search.js                     # Search implementation
│   ├── map.js                        # Data field mapping
│   └── adapter.js                    # Memory adapter for caching
└── tests/                            # Integration tests

API Endpoints

Country Endpoints

Endpoint	Method	Purpose	Query Parameters
/v1/googlemap/country	GET	List all countries	None
/v1/googlemap/country/:searchText	GET	Search countries	searchText (path param)
/v1/googlemap/country-code	GET	Get supported country codes	None

State Endpoints

Endpoint	Method	Purpose	Query Parameters
/v1/googlemap/state	GET	List states by country	country_code (required)
/v1/googlemap/state/:searchText	GET	Search states	searchText (path param)

City Endpoints

Endpoint	Method	Purpose	Query Parameters
/v1/googlemap/cities	GET	List cities by state	state_code, country_code
/v1/googlemap/cities/:searchText	GET	Search cities	searchText (path param)
/v1/googlemap/:searchText	GET	General location search	detail (optional)

Postal Code Endpoints

Endpoint	Method	Purpose	Query Parameters
/v1/googlemap/zip/:country_code/:state_name/:city_name	GET	Get postal codes	Path parameters
/v1/googlemap/:zip_code/:countryCode	GET	Lookup location by postal code	Path parameters

Data Models

Country Data Model

{
  id: 1,
  name: "United States",
  iso3: "USA",
  iso2: "US",
  numeric_code: "840",
  phone_code: "1",
  capital: "Washington",
  currency: "USD",
  currency_symbol: "$",
  tld: ".us",
  native: "United States",
  region: "Americas",
  subregion: "Northern America",
  latitude: "38.00000000",
  longitude: "-97.00000000",
  emoji: "🇺🇸",
  emojiU: "U+1F1FA U+1F1F8"
}

State Data Model

{
  id: 1,
  name: "California",
  country_id: 233,
  country_code: "US",
  country_name: "United States",
  state_code: "CA",
  type: "state",
  latitude: "36.77826100",
  longitude: "-119.41793240"
}

City Data Model

{
  id: 1,
  name: "Los Angeles",
  state_id: 1416,
  state_code: "CA",
  state_name: "California",
  country_id: 233,
  country_code: "US",
  country_name: "United States",
  latitude: "34.05223390",
  longitude: "-118.24368490",
  wikiDataId: "Q65"
}

Postal Code Data Model

{
  zip_code: "90001",
  place: "Los Angeles",
  state: "California",
  state_code: "CA",
  province: "Los Angeles",
  province_code: "037",
  community: "Downtown",
  community_code: "001",
  country_code: "US",
  latitude: "33.9731",
  longitude: "-118.2479",
  accuracy: 4
}

Usage Examples

Search Countries

List All Countries

// Request
GET /v1/googlemap/country

// Response
{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "id": 233,
      "name": "United States",
      "iso3": "USA",
      "iso2": "US",
      "phone_code": "1",
      "currency": "USD",
      "emoji": "🇺🇸"
      // ... more fields
    }
    // ... more countries
  ]
}

Search Country by Name

// Request
GET /v1/googlemap/country/united

// Response
{
  "success": true,
  "message": "Country Searching successfully!",
  "data": [
    {
      "id": 233,
      "name": "United States",
      // ... country details
    },
    {
      "id": 229,
      "name": "United Kingdom",
      // ... country details
    }
  ]
}

Search States

Get States by Country

// Request
GET /v1/googlemap/state?country_code=US

// Response
{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "id": 1416,
      "name": "California",
      "country_code": "US",
      "state_code": "CA",
      "latitude": "36.77826100",
      "longitude": "-119.41793240"
    }
    // ... more states
  ]
}

Search States by Name

// Request
GET /v1/googlemap/state/california

// Response
{
  "success": true,
  "message": "State Searching successfully!",
  "data": [
    {
      "id": 1416,
      "name": "California",
      "country_code": "US",
      "state_code": "CA",
      // ... state details
    }
  ]
}

Search Cities

Get Cities by State

// Request
GET /v1/googlemap/cities?state_code=CA&country_code=US

// Response
{
  "success": true,
  "message": "City Searching successfull!",
  "data": [
    {
      "id": 111,
      "name": "Los Angeles",
      "state_code": "CA",
      "state_name": "California",
      "country_code": "US",
      "latitude": "34.05223390",
      "longitude": "-118.24368490"
    }
    // ... more cities
  ]
}

Search Cities by Name

// Request
GET /v1/googlemap/cities/angeles

// Response
{
  "success": true,
  "message": "City Searching successfully!",
  "data": [
    {
      "id": 111,
      "name": "Los Angeles",
      "state_code": "CA",
      "country_code": "US"
      // ... city details
    },
    {
      "id": 3621,
      "name": "Los Angeles",
      "state_code": "CHI",
      "country_code": "CL"
      // ... another Los Angeles
    }
  ]
}

Postal Code Lookup

Get Postal Codes by Location

// Request
GET /v1/googlemap/zip/US/california/los angeles

// Response
{
  "success": true,
  "message": "SUCCESS",
  "data": [
    [
      4,                    // accuracy
      "Downtown",           // community
      "001",               // community_code
      "US",                // country_code
      "33.9731",           // latitude
      "-118.2479",         // longitude
      "Los Angeles",       // place
      "Los Angeles",       // province
      "037",               // province_code
      "California",        // state
      "CA",                // state_code
      "90001"              // zip_code
    ]
    // ... more ZIP codes (may have duplicates for sub-areas)
  ]
}

Lookup Location by Postal Code

// Request
GET /v1/googlemap/90001/US

// Response
{
  "success": true,
  "message": "Zip Code Found Successfully",
  "result": [
    {
      "id": 111,
      "name": "Los Angeles",
      "state_code": "CA",
      "region_code": "90001",
      "country_code": "US"
      // ... city details
    }
  ]
}

General Location Search

Simple Search (Names Only)

// Request
GET /v1/googlemap/springfield

// Response
{
  "success": true,
  "message": "Searching successfully!",
  "data": [
    {
      "name": "Springfield",
      "state": "Illinois",
      "country": "United States"
    },
    {
      "name": "Springfield",
      "state": "Massachusetts",
      "country": "United States"
    }
    // ... more Springfields
  ]
}

Detailed Search (Full Objects)

// Request
GET /v1/googlemap/springfield?detail=true

// Response
{
  "success": true,
  "message": "Searching successfully!",
  "data": [
    {
      "name": {
        "id": 1234,
        "name": "Springfield",
        "state_id": 14,
        "country_code": "US"
        // ... full city object
      },
      "state": {
        "id": 14,
        "name": "Illinois",
        "country_code": "US"
        // ... full state object
      },
      "country": {
        "id": 233,
        "name": "United States"
        // ... full country object
      }
    }
    // ... more results
  ]
}

Error Handling

Standard Error Response

{
  "success": false,
  "errno": 404,
  "message": "City not found",
  "additional_info": "Error details"
}

Error Scenarios

Error Code	Error Type	Cause	Resolution
400	Bad Request	Missing required parameters	Provide required query/path parameters
404	Not Found	No matching data found	Verify search criteria
404	Not Found	Invalid country code	Check country code format
500	Server Error	Data file not found	Contact backend team

Error Examples

Missing Required Parameter

// Request
GET /v1/googlemap/state
// Missing country_code

// Response
{
  "success": false,
  "errno": 400,
  "message": "Please provide a country code"
}

No Results Found

// Request
GET /v1/googlemap/cities/nonexistentcity

// Response
{
  "success": false,
  "errno": 404,
  "message": "City not found"
}

Invalid Country Code

// Request
GET /v1/googlemap/zip/XX/california/los angeles
// XX is not a valid country code

// Response
{
  "success": false,
  "errno": 404,
  "message": "Zip Code not found"
}

Supported Countries (Postal Codes)

The following 90+ countries have postal code data available in the assets/ directory:

Americas: US, CA, BR, MX, AR, CL, CO, CR, DO, GT, GF, GP, GU, MQ, PM, PR, UY, VI

Europe: AT, BE, BG, BY, CH, CZ, DE, DK, ES, FI, FO, FR, GB, GG, GL, HR, HU, IE, IM, IS, IT, JE, LI, LT, LU, LV, MC, MD, MK, MT, NL, NO, PL, PT, RE, RO, RU, SE, SI, SJ, SK, SM, VA, WF

Asia: BD, IN, JP, LK, MY, PH, PK, TH, TR

Oceania: AS, AU, FM, MH, MP, NC, NZ, PW

Africa: DZ, ZA, YT

Other: AD, AX, BM

Z1P Library

The integration uses a custom Z1P library for postal code lookup:

Library Structure

// src/index.js - Main wrapper
const z1p = (codes, options) => {
  // codes: Array of country codes
  // options: { memorize: false, adapter: memoryAdapter }

  return {
    raw: comp => {
      /* Raw search */
    },
    findBy: (key, value) => {
      /* Search by field */
    },
  };
};

Search Implementation

// src/search.js - Search logic
module.exports = (data, comp) => {
  // data: Country code string or data array
  // comp: Comparison function
  // Loads data from assets/{country_code}
  // Applies comparison function
  // Returns filtered results
};

Data Mapping

// src/map.js - Field mapping
const MAP = {
  accuracy: 0,
  community: 1,
  community_code: 2,
  country_code: 3,
  latitude: 4,
  longitude: 5,
  place: 6,
  province: 7,
  province_code: 8,
  state: 9,
  state_code: 10,
  zip_code: 11,
};

// Converts array format to object format

Performance Considerations

Data Loading

• On-Demand Loading: Postal code files loaded only when needed
• Memory Usage: Large datasets (~194 files) - consider memory limits
• Caching: Optional memory adapter for repeated queries

Search Optimization

• Case-Insensitive: All searches use toLowerCase() for matching
• Partial Matching: Uses includes() for flexible search
• Array Filtering: In-memory filtering for fast results

Best Practices

// ✅ Good: Specific country search
GET /v1/googlemap/state?country_code=US

// ✅ Good: Limited search text
GET /v1/googlemap/cities/los

// ❌ Avoid: Very broad searches that return thousands of results
GET /v1/googlemap/cities/a

// ❌ Avoid: Repeated calls without caching
// Consider client-side caching for repeated queries

Use Cases

Address Validation

// 1. User enters: "Los Angeles, CA"
// 2. Search city
GET /v1/googlemap/cities/los angeles

// 3. Validate state code
GET /v1/googlemap/state?country_code=US

// 4. Get postal codes for the area
GET /v1/googlemap/zip/US/california/los angeles

Location Autocomplete

// User types: "spri"
GET / v1 / googlemap / springfield;

// Returns all cities matching "spri" with state/country context

Postal Code Lookup

// User enters ZIP: "90001"
GET / v1 / googlemap / 90001 / US;

// Returns city and state information

Country Selection Dropdown

// Load all countries for dropdown
GET / v1 / googlemap / country;

// Returns complete list with ISO codes and phone codes

Integration Dependencies

Required Packages

{
  "express": "^4.x"
}

Internal Dependencies

• Utilities: Error handling (catch-errors)
• Data Files: JSON datasets in data/ directory
• Asset Files: Country-specific postal code files

Testing

Test Structure

tests/
├── googlemap.test.js     # Main integration tests
└── fixtures/
    └── sample-data.json  # Test data

Test Coverage Areas

• Country search functionality
• State filtering by country
• City search with hierarchy
• Postal code lookup
• Error handling for invalid inputs
• Data integrity checks

Monitoring and Maintenance

Health Checks

• Data file availability
• Response time monitoring
• Search result accuracy
• Memory usage tracking

Maintenance Tasks

• Data Updates: Periodic updates to geographic data
• Country Coverage: Add new countries to postal code assets
• Data Validation: Verify data accuracy and completeness
• Performance Tuning: Optimize search algorithms as needed

Common Issues and Solutions

Issue: "Zip Code not found"

Cause: Country code not in supported list
Solution: Check /v1/googlemap/country-code for supported countries

Issue: "State not found"

Cause: Invalid country_code parameter
Solution: Use ISO2 country codes (e.g., "US", "CA", "GB")

Issue: Duplicate postal codes

Cause: City has multiple sub-areas with same ZIP
Solution: This is expected; filter by additional criteria if needed

Issue: Large result sets

Cause: Broad search terms
Solution: Use more specific search criteria or implement pagination

Related Documentation

• Address Validation Service (Internal)
• Location-Based Features (Frontend)

---

Last Updated: December 2024
Status: Active (Local Data Service)
Complexity: LOW-MEDIUM
Maintenance: Data updates quarterly