Skip to main content

​
Trip Management

MayTravel provides a hierarchical trip management system that organizes your travels from high-level planning down to individual activity details. Each trip contains a structured itinerary with stops, timing, and location information.

​
Trip Structure Overview

Trips follow a clear organizational hierarchy:
1

Trip Container

The top level holds your trip title, destination, accommodation location, and travel dates.
2

Stop Sequence

Each trip contains an ordered list of stops representing places to visit during your journey.
3

Points of Interest

Stops link to detailed POI records with names, categories, and location data.
4

Timing Details

Every stop includes arrival time, departure time, and visit order for optimal planning.

​
Creating a New Trip

Start planning by creating a trip linked to your user account: 
POST /api/users/:id/trips

{
  "title": "Exploring Tokyo",
  "lat": 35.6762,
  "lng": 139.6503,
  "arrive_date": "2026-09-01",
  "leave_date": "2026-09-07"
}

Response:
{
  "message": "trip created successfully"
}
The lat and lng coordinates represent your accommodation or base location (shelter) during the trip. The AI uses this to optimize travel times.

​
Trip Properties

Each trip contains the following information:
​
title
string
required
A descriptive name for your trip (e.g., “Summer in Barcelona”, “Weekend Getaway to Rome”).
​
shelter
Point
required
Geographic coordinates of your accommodation stored as a PostGIS Point geometry. This serves as your home base.
​
arrive_date
date
required
The date you arrive at your destination.
​
leave_date
date
required
The date you depart from your destination.
​
user_id
integer
required
Links the trip to your user account.

​
Viewing Your Trips

​
View All Trips by User

Get a complete list of all your trips: 
GET /api/users/:id/trips

Response:
{
  "user_id": 1,
  "username": "traveler123",
  "trips": [
    {
      "id": 1,
      "title": "Exploring Tokyo",
      "shelter": { "type": "Point", "coordinates": [139.6503, 35.6762] },
      "arrd": "2026-09-01",
      "levd": "2026-09-07"
    },
    {
      "id": 2,
      "title": "Barcelona Culture Tour",
      "shelter": { "type": "Point", "coordinates": [2.1686, 41.3874] },
      "arrd": "2026-10-15",
      "levd": "2026-10-20"
    }
  ]
}

​
View Detailed Trip Information

Retrieve a complete itinerary with all stops: 
GET /api/trips/:id

Response:
{
  "title": "Exploring Tokyo",
  "shelter": { "type": "Point", "coordinates": [139.6503, 35.6762] },
  "arrive_date": "2026-09-01",
  "leave_date": "2026-09-07",
  "stops": [
    {
      "id": 1,
      "name": "Senso-ji Temple",
      "category": "Historical Sites",
      "order": 1,
      "coming": "2026-09-01T09:00:00Z",
      "leaving": "2026-09-01T11:00:00Z"
    },
    {
      "id": 2,
      "name": "Tokyo Skytree",
      "category": "Landmarks",
      "order": 2,
      "coming": "2026-09-01T14:00:00Z",
      "leaving": "2026-09-01T17:00:00Z"
    },
    {
      "id": 3,
      "name": "Shibuya Crossing",
      "category": "Urban Experiences",
      "order": 3,
      "coming": "2026-09-01T18:30:00Z",
      "leaving": "2026-09-01T20:00:00Z"
    }
  ]
}

​
Understanding Stops

Stops are the individual activities and places in your itinerary:

Stop Order

Sequential numbers (1, 2, 3…) indicate the recommended order to visit locations.

Timing

Each stop includes arrival and departure times for precise planning.

POI Details

Linked to the POI catalog for rich information about each location.

Category Tags

Categorized by type (Historical Sites, Restaurants, Parks, etc.) for easy filtering.

​
Adding Stops to Your Trip

Build out your itinerary by adding stops: 
POST /api/stops

{
  "trip_id": 1,
  "poi_catalog_id": 42,
  "stop_order": 4,
  "arrival_time": "2026-09-02T10:00:00Z",
  "departure_time": "2026-09-02T12:30:00Z"
}

Response:
{
  "message": "Stop added correctly"
}
The AI typically generates stops automatically, but you can manually add stops to customize your itinerary or add personal favorites.

​
Deleting a Trip

Remove a trip you no longer need: 
DELETE /api/trips/:id

Response:
{
  "message": "Trip Deleted Successfully"
}
Deleting a trip also removes all associated stops and itinerary data. This action cannot be undone.

​
Browsing All Trips

Admins or authorized users can view all trips in the system: 
GET /api/trips

Response:
[
  {
    "id": 1,
    "user_id": 1,
    "title": "Exploring Tokyo",
    "shelter": { "type": "Point", "coordinates": [139.6503, 35.6762] },
    "arrive_date": "2026-09-01",
    "leave_date": "2026-09-07"
  },
  {
    "id": 2,
    "user_id": 2,
    "title": "Paris in Spring",
    "shelter": { "type": "Point", "coordinates": [2.3522, 48.8566] },
    "arrive_date": "2026-04-10",
    "leave_date": "2026-04-17"
  }
]

​
Geographic Data

MayTravel uses PostGIS for advanced geographic features:
Shelter locations are stored as PostGIS Point geometries in SRID 4326 (WGS 84), the standard for GPS coordinates.
Points are represented as [longitude, latitude]. Note that longitude comes first in GeoJSON format.
The system can perform distance calculations, proximity searches, and route optimization using spatial functions.
Coordinates integrate seamlessly with mapping services like Google Maps Platform for visualization.

​
Trip Planning Workflow

Follow this typical workflow for trip planning:
1

Create Trip

Start by creating a trip with your destination, dates, and accommodation location.
2

AI Generation

The AI analyzes your profile interests and generates a personalized itinerary with stops.
3

Review Itinerary

View your complete trip to see all recommended stops, timing, and categories.
4

Customize Stops

Add, remove, or reorder stops to perfect your itinerary.
5

Explore Details

Click through to POI details to learn more about each location.
6

Export or Share

Use your completed itinerary during your travels or share it with companions.

​
Best Practices

Accurate Shelter Location

Use the exact coordinates of your hotel or accommodation for optimal travel time calculations.

Realistic Time Frames

Don’t over-pack your itinerary. Allow buffer time between stops for travel and spontaneity.

Logical Stop Order

Keep stops in a geographic sequence to minimize backtracking across the city.

Category Balance

Mix different stop categories (culture, food, nature) for a well-rounded experience.

​
Learn More

AI Trip Planning

Understand how AI generates your itineraries

Points of Interest

Explore the POI catalog and available locations

Trip API Reference

View complete API documentation for trips

Stops API

Learn how to work with stops programmatically

Build docs developers (and LLMs) love

Get started for freeTalk to us