Midway@ API Documentation

Integrate fair travel time meetup planning into your applications. Our RESTful API helps you build features that find perfect meeting spots where everyone has balanced commutes.

🚀 Quick Start

Get started with the Midway@ API in minutes. Perfect for developers building group coordination features, event planning apps, or workplace tools that need smart meeting location suggestions.

// Create a new meetup session
const response = await fetch('https://www.midway.at/api/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    hostName: 'Alice',
    hostAddress: '123 Main St, New York, NY',
    venueQuery: 'coffee shop with wifi',
    participants: [
      { name: 'Bob', address: '456 Oak Ave, Brooklyn, NY' },
      { name: 'Carol', address: '789 Pine St, Queens, NY' }
    ]
  })
})
const session = await response.json()
console.log('Session created:', session.shareUrl)

🔌 Core API Endpoints

Create Session

POST/api/sessions

Creates a new meetup planning session with participants and venue preferences. Returns recommendations for venues with fair travel times for all participants.

Request Body:

{
  "hostName": "string",
  "hostEmail": "string (optional)",
  "hostAddress": "string",
  "hostTransport": "driving|walking|transit|bicycling",
  "venueQuery": "string",
  "participants": [
    {
      "name": "string",
      "email": "string (optional)",
      "address": "string", 
      "transportMode": "driving|walking|transit|bicycling"
    }
  ]
}

Response:

{
  "sessionId": "string",
  "shareToken": "string",
  "shareUrl": "string",
  "venues": [
    {
      "id": "string",
      "name": "string",
      "address": "string",
      "rating": number,
      "priceLevel": number,
      "fairnessScore": number,
      "maxTravelTime": number,
      "aiDescription": "string",
      "travelTimes": {
        "participantId": {
          "duration": number,
          "distance": number,
          "mode": "string"
        }
      }
    }
  ]
}

Get Session Details

GET/api/sessions/join/{shareToken}

Retrieves session details including all participants, venue recommendations, and current voting status. Use this endpoint to build collaborative interfaces where participants can view and vote on venues.

Example Response:

{
  "sessionId": "string",
  "hostName": "string",
  "venueQuery": "string",
  "status": "active|completed",
  "participants": [...],
  "venues": [...],
  "votes": {
    "venueId": {
      "count": number,
      "voters": ["participantName1", "participantName2"]
    }
  }
}

Vote on Venues

POST/api/sessions/{sessionId}/vote

Allows participants to vote for their preferred venues. Supports both single votes and ranked preferences. Essential for building collaborative decision-making features.

Request Body:

{
  "token": "shareToken",
  "participantName": "string",
  "venueId": "string",
  "action": "upvote|downvote|remove"
}

⚡ Advanced Features

🧠 AI-Powered Descriptions

Every venue recommendation includes AI-generated descriptions that explain why it's a good fit for your specific group and venue requirements.

"aiDescription": "Perfect for your coffee meeting - spacious seating, reliable WiFi, and quiet atmosphere ideal for conversation."

⚖️ Fairness Scoring

Proprietary algorithm that balances travel times across all participants, not just geographic distance. Ensures no one gets stuck with an unfair commute.

"fairnessScore": 0.92, // Higher = more fair "maxTravelTime": 18 // Minutes for furthest participant

🚇 Multi-Modal Transport

Supports driving, walking, public transit, and cycling. Calculates real-time travel times using live traffic and transit data.

"transportMode": "transit", "duration": 23, // Live travel time in minutes "distance": 3.2 // Distance in kilometers

🔗 Share Links

Generate shareable links that work without requiring participants to install apps or create accounts. Perfect for quick group coordination.

"shareUrl": "https://www.midway.at/join/abc123", // No sign-up required for participants

💡 Common Use Cases

Event Planning Apps

• Add fair meetup planning to event platforms
• Integrate with calendar applications
• Build group coordination features
• Optimize corporate event locations

Workplace Tools

• Team meeting location optimization
• Client meeting venue selection
• Company retreat planning
• Remote team coordination

Social Apps

• Dating app meetup suggestions
• Friend group coordination
• Community event planning
• Study group location finder

Travel & Navigation

• Multi-person route optimization
• Tourist group coordination
• Public transit integration
• Accessibility-aware planning

🔒 Authentication & Limits

Rate Limits

• Free Tier: 100 requests/hour
• Sessions: 50 active sessions
• Participants: 20 per session
• Venues: 15 recommendations per query

Authentication

• API Key: Contact us for access
• Session Tokens: Temporary, secure
• CORS: Configurable origins
• HTTPS: Required for all requests

Contact Us

Contact us for API access and integration support. We're here to help you build amazing group coordination features. Reach out to us at kapil@midway.at.