MealViewer API Client

TypeScript/JavaScript client for the MealViewer School Lunch Menu API.

Features

• 🔍 Search for schools by name, district, city, or state
• 📅 Fetch school lunch menus by date
• 🍎 Access nutrition information and allergens
• 📦 TypeScript support with full type definitions
• 🛡️ Error handling and type safety
• 🐛 Optional debug logging
• ✅ Public API (no authentication required)

Installation

npm install @brandcast_app/mealviewer-api-client

or

yarn add @brandcast_app/mealviewer-api-client

Quick Start

import { MealViewerClient } from '@brandcast_app/mealviewer-api-client';

// Create a client instance
const client = new MealViewerClient({
  debug: true, // Optional: enable debug logging
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
});

// Get today's menu for a school
const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD

const result = await client.getMenu({
  schoolName: 'ElmwoodElementary',
  startDate: today,
});

// Display menus
for (const menu of result.menus) {
  console.log(`\nMenu for ${menu.date.toDateString()}`);
  console.log(`School: ${menu.school.name}`);

  for (const meal of menu.meals) {
    console.log(`\n${meal.mealPeriod}:`);

    for (const line of meal.cafeteriaLines) {
      console.log(`  ${line.name}:`);

      for (const item of line.items) {
        console.log(`    - ${item.name} (${item.servingSize})`);
      }
    }
  }
}

API Reference

Constructor

new MealViewerClient(config?)

Create a new MealViewer API client.

Parameters:

• config (optional): Configuration object
  • baseURL (string): API base URL (default: https://api.mealviewer.com/api/v4)
  • timeout (number): Request timeout in ms (default: 30000)
  • userAgent (string): Custom user agent
  • debug (boolean): Enable debug logging (default: false)

Example:

const client = new MealViewerClient({ debug: true });

Methods

searchSchools(query: string): Promise<SchoolSearchResult[]>

Search for schools by name, district, city, or state.

Parameters:

• query (string): Search query (minimum 2 characters)

Returns: Promise with array of matching schools (empty array if no matches)

Example:

// Search for schools
const results = await client.searchSchools('elmwood');

console.log(`Found ${results.length} schools`);
for (const school of results) {
  console.log(`${school.name} - ${school.district}`);
  console.log(`  ${school.city}, ${school.state}`);
  console.log(`  Identifier: ${school.identifier}`);
}

Search Tips:

• Searches across school name, district, city, state, and identifier
• Case-insensitive matching
• Partial matches supported (e.g., "spring" matches "Springfield")
• Results are cached for 1 hour for better performance

getMenu(request: GetMenuRequest): Promise<GetMenuResponse>

Get menu for a school and date range.

Parameters:

• request.schoolName (string): School identifier (e.g., "ElmwoodElementary")
• request.startDate (Date | string): Start date (YYYY-MM-DD or Date object)
• request.endDate (Date | string, optional): End date (defaults to startDate)

Returns: Promise with menus and school information

Example:

// Get menu for single day
const result = await client.getMenu({
  schoolName: 'ElmwoodElementary',
  startDate: '2025-01-15',
});

// Get menu for date range (week)
const weekResult = await client.getMenu({
  schoolName: 'ElmwoodElementary',
  startDate: '2025-01-13', // Monday
  endDate: '2025-01-17',   // Friday
});

console.log(`Found ${weekResult.menus.length} days of menus`);

Type Definitions

SchoolSearchResult

interface SchoolSearchResult {
  identifier: string;     // School identifier for getMenu() calls
  name: string;           // School name
  district: string;       // School district name
  city?: string;          // City
  state?: string;         // State (e.g., "MO", "KS")
  address?: string;       // Street address
  zip?: string;           // ZIP code
}

GetMenuResponse

interface GetMenuResponse {
  menus: DailyMenu[];
  school: MealViewerSchool;
}

DailyMenu

interface DailyMenu {
  date: Date;
  school: MealViewerSchool;
  meals: MenuBlock[];
}

MenuBlock

interface MenuBlock {
  mealPeriod: 'Breakfast' | 'Lunch' | 'Dinner' | 'Snack';
  cafeteriaLines: CafeteriaLine[];
}

CafeteriaLine

interface CafeteriaLine {
  name: string;
  items: MenuItem[];
}

MenuItem

interface MenuItem {
  name: string;
  altName?: string;
  description?: string;
  type: 'Entree' | 'Side' | 'Vegetable' | 'Fruit' | 'Milk' | 'Condiment' | string;
  servingSize: string;
  nutrition?: NutritionFacts;
  allergens?: string[];
}

MealViewerSchool

interface MealViewerSchool {
  name: string;
  address: string;
  city: string;
  state?: string;
  latitude?: number;
  longitude?: number;
}

Error Handling

The client throws MealViewerError with a specific error code:

class MealViewerError extends Error {
  code: 'SCHOOL_NOT_FOUND' | 'API_ERROR' | 'INVALID_DATE' | 'NETWORK_ERROR';
}

Example:

try {
  const result = await client.getMenu({
    schoolName: 'InvalidSchool',
    startDate: '2025-01-15',
  });
} catch (error) {
  if (error instanceof MealViewerError) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);

    if (error.code === 'SCHOOL_NOT_FOUND') {
      console.log('Please check the school name and try again.');
    }
  }
}

Finding School Names

Use the searchSchools() method to find schools:

// Search for schools in Springfield
const schools = await client.searchSchools('springfield');

// Search by district
const districtSchools = await client.searchSchools('blue valley');

// Search by state
const moSchools = await client.searchSchools('MO');

Once you find your school, use the identifier field to fetch menus:

const results = await client.searchSchools('elmwood');
if (results.length > 0) {
  const school = results[0];

  const menu = await client.getMenu({
    schoolName: school.identifier, // Use the identifier
    startDate: '2025-01-15',
  });
}

Complete Example

import { MealViewerClient, MealViewerError } from '@brandcast_app/mealviewer-api-client';

async function main() {
  const client = new MealViewerClient({ debug: true });

  try {
    // Step 1: Search for a school
    console.log('Searching for schools...');
    const schools = await client.searchSchools('elmwood');

    if (schools.length === 0) {
      console.log('No schools found');
      return;
    }

    console.log(`Found ${schools.length} school(s):`);
    for (const school of schools) {
      console.log(`  - ${school.name} (${school.district})`);
      console.log(`    ${school.city}, ${school.state}`);
    }

    // Step 2: Get this week's menus for the first school
    const selectedSchool = schools[0];
    console.log(`\nFetching menus for: ${selectedSchool.name}`);

    const monday = new Date('2025-01-13');
    const friday = new Date('2025-01-17');

    const result = await client.getMenu({
      schoolName: selectedSchool.identifier,
      startDate: monday,
      endDate: friday,
    });

    console.log(`\n${result.school.name}`);
    console.log(`${result.school.address}, ${result.school.city}`);
    console.log(`\nMenus for ${result.menus.length} days:\n`);

    for (const menu of result.menus) {
      console.log(`\n=== ${menu.date.toDateString()} ===`);

      const lunch = menu.meals.find(m => m.mealPeriod === 'Lunch');

      if (lunch) {
        for (const line of lunch.cafeteriaLines) {
          console.log(`\n${line.name}:`);
          for (const item of line.items) {
            console.log(`  • ${item.name} - ${item.servingSize}`);
            if (item.description) {
              console.log(`    ${item.description}`);
            }
          }
        }
      }
    }

  } catch (error) {
    if (error instanceof MealViewerError) {
      console.error(`\n❌ ${error.code}: ${error.message}`);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

main();

Development

Building

npm install
npm run build

Testing

npm test
npm run test:coverage

Use Cases

This client is useful for:

• 📱 Family information displays (FamilyCast)
• 🏫 School district apps
• 📧 Parent notification systems
• 🤖 Chat bot integrations (e.g., Claude Desktop via MCP)
• 📊 Menu analytics and tracking

Related Projects

• mealviewer-mcp-server - MCP server for Claude Desktop
• FamilyCast - Family information displays

Legal

This is an unofficial library and is not affiliated with, endorsed by, or connected to MealViewer. The MealViewer API is public and does not require authentication.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• 🐛 Report Issues
• 💬 Discussions

Changelog

0.2.0

• 🔍 Added searchSchools() method for finding schools
• 📚 School database with 20+ Missouri/Kansas area schools
• 💾 Automatic caching of school database (1 hour TTL)
• 📖 Updated documentation with search examples
• 🎯 Enhanced type exports with SchoolSearchResult

0.1.0 (Initial Release)

• ✨ Initial implementation
• 📅 Fetch menus by date range
• 🍎 Access menu items, nutrition, allergens
• 📦 Full TypeScript support
• 🐛 Debug logging option