How City Data API Drove 340% Higher ROI for Hyperlocal Marketing Campaigns

// Build intelligent trade areas from city data
async function buildTradeArea(storeLocation: Location) {
  const radius = 15; // miles - initial search radius

  // Get all cities within potential trade area
  const nearbyCities = await moduleAppClient.v1ListCities.v1ListCitiesAction({
    latitude: storeLocation.lat,
    longitude: storeLocation.lng,
    radius: radius,
    radiusUnit: 'mi',
    limit: 100
  });

  // Score each city for trade area fit
  const scoredCities = nearbyCities.data.map(city => {
    const distance = calculateDistance(storeLocation, city);
    const drivingTime = await getDrivingTime(storeLocation, city);

    // Factors that make a city part of your trade area
    const demographicScore = scoreDemographics(city, targetCustomer);
    const economicScore = scorePurchasingPower(city);
    const accessibilityScore = scoreAccessibility(city);
    const competitionScore = scoreCompetition(city, competitors);

    // Weighted score (customize weights for your business)
    const tradeAreaScore = (
      (demographicScore * 0.35) +
      (economicScore * 0.30) +
      (accessibilityScore * 0.25) +
      (competitionScore * 0.10)
    );

    return {
      ...city,
      distance,
      drivingTime,
      tradeAreaScore,
      isHighPriority: tradeAreaScore > 0.7
    };
  });

  // Filter to actual trade area cities
  return scoredCities.filter(c => c.tradeAreaScore > 0.5);
}

// Use for targeting
const storeTradeArea = await buildTradeArea(downtownStore);

// Create hyperlocal audience segments
const highValueTargets = storeTradeArea
  .filter(c => c.isHighPriority)
  .map(c => c.postalCodes)
  .flat();

const secondaryTargets = storeTradeArea
  .filter(c => !c.isHighPriority && c.tradeAreaScore > 0.65)
  .map(c => c.postalCodes)
  .flat();

// Create audience segments based on city intelligence
interface HyperlocalSegment {
  name: string;
  postalCodes: string[];
  demographics: DemographicProfile;
  messaging: MessagingStrategy;
  budgetAllocation: number; // percentage
}

async function buildHyperlocalSegments(
  tradeArea: City[],
  product: Product
): Promise<HyperlocalSegment[]> {
  const segments: HyperlocalSegment[] = [];

  // Segment 1: High-income family areas
  const affluentFamilies = tradeArea.filter(city =>
    city.medianIncome > 120000 &&
    city.population.age25_44 > 0.35 &&
    city.household.hasChildren > 0.40
  );

  if (affluentFamilies.length > 0) {
    segments.push({
      name: 'Affluent Families',
      postalCodes: affluentFamilies.map(c => c.postalCodes).flat(),
      demographics: {
        income: 'high',
        age: '25-44',
        familyStatus: 'families'
      },
      messaging: {
        headline: 'Quality Your Family Deserves',
        valueProps: ['premium quality', 'family value', 'convenience'],
        tone: 'aspirational'
      },
      budgetAllocation: 40
    });
  }

  // Segment 2: Urban professionals
  const urbanProfessionals = tradeArea.filter(city =>
    city.urbanDensity > 0.7 &&
    city.population.age25_34 > 0.40 &&
    city.education.bachelorsOrHigher > 0.50
  );

  if (urbanProfessionals.length > 0) {
    segments.push({
      name: 'Urban Professionals',
      postalCodes: urbanProfessionals.map(c => c.postalCodes).flat(),
      demographics: {
        income: 'medium-high',
        age: '25-34',
        lifestyle: 'professional'
      },
      messaging: {
        headline: 'Built for Your Lifestyle',
        valueProps: ['time-saving', 'smart choice', 'social proof'],
        tone: 'confident'
      },
      budgetAllocation: 35
    });
  }

  // Segment 3: Value-conscious segments
  const valueConscious = tradeArea.filter(city =>
    city.medianIncome < 65000 &&
    city.costOfLivingIndex > 100 &&
    city.population.age45_64 > 0.30
  );

  if (valueConscious.length > 0) {
    segments.push({
      name: 'Value Seekers',
      postalCodes: valueConscious.map(c => c.postalCodes).flat(),
      demographics: {
        income: 'medium',
        age: '45-64',
        priority: 'value'
      },
      messaging: {
        headline: 'Smart Savings Start Here',
        valueProps: ['everyday value', 'smart choice', 'reliability'],
        tone: 'practical'
      },
      budgetAllocation: 25
    });
  }

  return segments;
}