AIDP Protocol

The open protocol for AI-accessible local business data

AIDP (AI Discovery Protocol) is an open standard that defines how local business data should be structured for AI platforms. Like HTTP for web traffic, AIDP standardizes the data exchange between local businesses and AI assistants.

🚀 Quick Start

npm install @aidp/protocol

import { BusinessProfile, validateBusinessProfile } from '@aidp/protocol';

// Create a business profile
const business: BusinessProfile = {
  id: 'biz_123',
  name: 'Blue Bottle Coffee',
  category: 'Coffee Shop',
  location: {
    address: '123 Main St, San Francisco, CA 94102',
    coordinates: { lat: 37.7749, lng: -122.4194 }
  },
  contact: {
    phone: '+1-555-0123',
    website: 'https://bluebottlecoffee.com'
  },
  // ... more fields
};

// Validate the profile
const validation = validateBusinessProfile(business);
if (validation.valid) {
  console.log('✅ Valid AIDP business profile');
} else {
  console.error('❌ Validation errors:', validation.errors);
}

📋 Features

• 🔧 TypeScript Support - Full type definitions for all AIDP entities
• ✅ Schema Validation - Built-in validation using JSON Schema
• 🛠️ MCP Tools - Ready-to-use MCP tool definitions
• 📊 Analytics Types - Upstream metrics and intent journey types
• 🔄 Migration Helpers - Convert from Google Business Profile, Yelp, etc.
• 📖 Comprehensive Docs - Complete API reference and examples

🏗️ Core Concepts

Business Profile

The foundation of AIDP - a comprehensive business data structure:

import { BusinessProfile } from '@aidp/protocol';

const profile: BusinessProfile = {
  // Basic Information
  id: 'unique_business_id',
  name: 'Business Name',
  category: 'Primary Category',
  description: 'Business description',
  
  // Location
  location: {
    address: 'Full address',
    coordinates: { lat: 37.7749, lng: -122.4194 },
    neighborhood: 'SOMA'
  },
  
  // Contact Information
  contact: {
    phone: '+1-555-0123',
    email: '[email protected]',
    website: 'https://business.com'
  },
  
  // Services & Pricing
  services: [
    {
      id: 'service_1',
      name: 'Service Name',
      description: 'Service description',
      price: 25.00,
      duration: 60,
      bookable: true
    }
  ],
  
  // Operating Hours
  availability: {
    schedule: {
      monday: { open: '09:00', close: '17:00' },
      tuesday: { open: '09:00', close: '17:00' }
      // ... other days
    },
    timezone: 'America/Los_Angeles'
  },
  
  // AI-Exclusive Content
  exclusiveContent: {
    insiderTips: ['Hidden menu items', 'Best times to visit'],
    localSecrets: ['Local knowledge only businesses know'],
    ownerStory: 'The story behind the business'
  },
  
  // Trust & Verification
  trustSignals: {
    verified: true,
    claimedByOwner: true,
    lastUpdated: '2024-11-15T10:30:00Z'
  }
};

Booking System

Standardized booking requests and responses:

import { BookingRequest, BookingResponse } from '@aidp/protocol';

const bookingRequest: BookingRequest = {
  businessId: 'biz_123',
  serviceId: 'service_1',
  date: '2024-11-20',
  time: '10:00',
  partySize: 2,
  customer: {
    name: 'John Doe',
    email: '[email protected]',
    phone: '+1-555-0199'
  }
};

const bookingResponse: BookingResponse = {
  id: 'booking_456',
  status: 'confirmed',
  confirmationCode: 'ABC123',
  // ... booking details
};

Upstream Analytics

Track AI discovery metrics:

import { UpstreamMetrics, IntentJourney } from '@aidp/protocol';

const metrics: UpstreamMetrics = {
  impressions: {
    total: 15420,
    byPlatform: {
      claude: 8234,
      chatgpt: 4892,
      perplexity: 2294
    }
  },
  citations: {
    total: 892,
    placement: {
      primary: 234,
      secondary: 445,
      tertiary: 213
    }
  },
  zeroClick: {
    total: 1247,
    visibility: 78.5
  }
};

🛠️ Validation

Validate any AIDP entity against the official schema:

import { 
  validateBusinessProfile,
  validateBookingRequest,
  validateReview 
} from '@aidp/protocol';

// Validate business profile
const profileValidation = validateBusinessProfile(businessData);
if (!profileValidation.valid) {
  console.error('Validation errors:', profileValidation.errors);
}

// Validate booking request
const bookingValidation = validateBookingRequest(bookingData);
if (bookingValidation.valid) {
  console.log('✅ Valid booking request');
}

// Custom validation with options
const validation = validateBusinessProfile(data, {
  strict: true,           // Strict validation mode
  allowAdditional: false, // Don't allow additional properties
  coerceTypes: true      // Coerce types when possible
});

🔧 MCP Integration

Ready-to-use MCP tool definitions:

import { MCPTools } from '@aidp/protocol';

// Get all AIDP MCP tools
const tools = MCPTools.getAllTools();

// Get specific tool definition
const searchTool = MCPTools.getSearchBusinessesTool();
const bookingTool = MCPTools.getCreateBookingTool();

// Use with MCP server
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: MCPTools.getAllTools()
  };
});

🔄 Migration Helpers

Convert from existing platforms:

import { 
  convertFromGoogleBusiness,
  convertFromYelp,
  convertFromFoursquare 
} from '@aidp/protocol';

// Convert Google Business Profile
const googleData = { /* Google Business Profile data */ };
const aidpProfile = convertFromGoogleBusiness(googleData);

// Convert Yelp Business data
const yelpData = { /* Yelp API response */ };
const aidpProfile2 = convertFromYelp(yelpData);

// Validate converted data
const validation = validateBusinessProfile(aidpProfile);

📊 Analytics & Insights

Work with upstream analytics data:

import { 
  UpstreamMetrics,
  IntentJourney,
  calculateShareOfVoice,
  analyzeIntentProgression 
} from '@aidp/protocol';

// Calculate share of voice
const shareOfVoice = calculateShareOfVoice(metrics, competitorMetrics);

// Analyze intent progression
const journey: IntentJourney = {
  id: 'journey_123',
  turns: [
    { turn: 1, intentScore: 20, query: 'coffee shops near me' },
    { turn: 2, intentScore: 35, query: 'best coffee downtown' },
    { turn: 3, intentScore: 65, query: 'Blue Bottle Coffee hours' },
    { turn: 4, intentScore: 88, query: 'book table at Blue Bottle' }
  ]
};

const analysis = analyzeIntentProgression(journey);
console.log(`Conversion probability: ${analysis.conversionProbability}`);

🎯 Use Cases

For AI Platform Developers

import { BusinessProfile, MCPTools } from '@aidp/protocol';

// Implement AIDP-compatible search
async function searchBusinesses(query: string, location: string) {
  const tool = MCPTools.getSearchBusinessesTool();
  const result = await callMCPTool(tool, { query, location });
  
  // Result is guaranteed to match AIDP schema
  return result.businesses as BusinessProfile[];
}

For Business Software Developers

import { BusinessProfile, validateBusinessProfile } from '@aidp/protocol';

// Export business data in AIDP format
function exportToAIDP(businessData: any): BusinessProfile {
  const aidpProfile: BusinessProfile = {
    id: businessData.id,
    name: businessData.name,
    // ... map your data to AIDP format
  };
  
  const validation = validateBusinessProfile(aidpProfile);
  if (!validation.valid) {
    throw new Error(`Invalid AIDP profile: ${validation.errors.join(', ')}`);
  }
  
  return aidpProfile;
}

For Local Business Platforms

import { convertFromGoogleBusiness, validateBusinessProfile } from '@aidp/protocol';

// Migrate existing business data
async function migrateToAIDP(googleBusinessData: any) {
  // Convert from Google Business Profile format
  const aidpProfile = convertFromGoogleBusiness(googleBusinessData);
  
  // Add AI-exclusive content
  aidpProfile.exclusiveContent = {
    insiderTips: ['Try our secret menu items'],
    localSecrets: ['Best parking is around the corner'],
    ownerStory: 'Family-owned since 1985'
  };
  
  // Validate before saving
  const validation = validateBusinessProfile(aidpProfile);
  if (validation.valid) {
    await saveBusinessProfile(aidpProfile);
  }
}

📚 API Reference

Core Types

• BusinessProfile - Complete business information
• BookingRequest - Booking request structure
• BookingResponse - Booking confirmation details
• Review - Customer review data
• UpstreamMetrics - AI discovery analytics
• IntentJourney - User intent progression

Validation Functions

• validateBusinessProfile(data, options?) - Validate business profile
• validateBookingRequest(data, options?) - Validate booking request
• validateBookingResponse(data, options?) - Validate booking response
• validateReview(data, options?) - Validate review data
• validateUpstreamMetrics(data, options?) - Validate analytics data

MCP Tools

• MCPTools.getAllTools() - Get all AIDP MCP tools
• MCPTools.getSearchBusinessesTool() - Search businesses tool
• MCPTools.getCreateBookingTool() - Create booking tool
• MCPTools.getGetReviewsTool() - Get reviews tool

Migration Helpers

• convertFromGoogleBusiness(data) - Convert Google Business Profile
• convertFromYelp(data) - Convert Yelp business data
• convertFromFoursquare(data) - Convert Foursquare venue data

Analytics Utilities

• calculateShareOfVoice(metrics, competitors) - Calculate market share
• analyzeIntentProgression(journey) - Analyze user intent
• calculateConversionProbability(journey) - Predict conversion

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/aidp-protocol/aidp-protocol.git
cd aidp-protocol
npm install
npm run build
npm test

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation: docs.aidp.dev
• Protocol Specification: aidp.dev/protocol
• GitHub Repository: github.com/aidp-protocol/aidp-protocol
• NPM Package: @aidp/protocol
• Community: Discord

🆘 Support

• Documentation: docs.aidp.dev
• Issues: GitHub Issues
• Email: [email protected]
• Discord: AIDP Protocol Community

AIDP Protocol - Making local business data accessible to AI, one protocol at a time. 🚀