Trip.Expert API - Trip Planning as a Service
The Trip.Expert API enables developers to consume trip planning services via HTTPS requests.
Simply send JSON requests to Trip.Expert from your server and act according to the responses you get back.
After a few calls to the API, you will have a well-planned and peronalized itinerary for the user.

Players


  • City - We support Paris and Tel Aviv right now.
  • User - Each city plan and itinerary belongs to specific user.
  • Plan - The general details about the city plan. Dates, preferences, user type, etc.
  • Itinerary - A collection of day routes, generated according to the city plan details.
  • Partner - You. The one the one that uses the API remotely.

    The Process


    The basic logic is as follow:
  • Create a new user
  • Create a city plan for the user with start and end date, preferences, hotel location, user type, etc.
  • Fetch an itinerary with list of sights for each day according to user's preferences and plan details.
  • Fetch info about the city and its guides so you will be able to effectively communicate the itinerary to the user.

    Trip.Expert API Ver. 1.1

    City API

    * Get city info
    Action: Fetch city guides grouped into Sights, Nearby, Food and Shopping. Additionaly, get general info such as city center location, possible user preferences and domain name.
    URL: https://trip.expert/api/city/info
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'city_id': CITY_ID            //mandatory. INTEGER.
    }
    Response
    {
        status: 1,
        name: 'Paris',
        domain: 'paris.trip.expert',
        city_center: {latitude: 48.857767008412, longitude: 2.3393567708378},
        support_email: 'paris-support@trip.expert',
        guides: {
            food: [...]
            nearby: [...]
            shopping: [...]
            sights: [...]
        },
        list_of_preferences: 'Landmarks, History, Culture, Art, Architecture, Churches, Science, Hidden gems, Kids, Outdoor, Food, Shopping, Nightlife, Out of town'
    }
    The Reponse to the /api/city/info call is quite big and contains info about all city guides.
    Use it once in a while to populate your server with the most up-to-date date.
    No need to pull this data more than once every few days.
    Note: Sights are important places while nearby are places of lessen importance.
    * Get city guide
    Action: Fetch specific city guide with its name, location, address, phone, web site, transportation and so forth.
    URL: https://trip.expert/api/city/guide
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'city_id': CITY_ID            //mandatory. INTEGER.
        'guide_id': GUIDE_ID          //mandatory. INTEGER.
    }
    Response
    {
        guide_id: GUIDE_ID,
        latitude: LATITUDE,
        longitude: LONGITUDE,
        title: '...',
        subtitle: '...',
        preface: '...',
        address: '...',
        duration_min: '...',
        duration_max: '...',
        duration_comment: '...',
        opening_hours: '...',
        phone: '...',
        transportation: '...',
        accessibility: '...',
        web_site: '...'
    }

    User API

    * Create a new user
    Action: Create a new user.
    URL: https://trip.expert/api/user/create
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_name': UNIQUE_USER_NAME,      //optional. STRING. If not set, unique username will be set automatically.
        'first_name': '...',                //optional. STRING.
        'last_name': '...',                 //optional. STRING.
        'email': '...',                     //optional. STRING.
        'is_email_verified': 1              //optional. INTEGER. 0:no / 1:yes.
    }
    Response
    {
        "status":1
        ,"msg":"New user created successfully."
        ,"details":{
            "user_id":USER_ID
            ,"username":NEW_USER_NAME
            ,"email_verification_code":"2ccc1a928588bcc6c7a0034edae7f5eb"
        }
    }
    Keep the returned user_id to reference this user by other API calls.
    * Get user details
    Action: Get user details according to user_id
    URL: https://trip.expert/api/user/details
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID     //mandatory. INTEGER.
    }
    Response
    {
      "status": 1,
      "details": {
        "user_id": USER_ID,
        "username": USERNAME,
        "first_name": FIRST_NAME,
        "last_name": LAST_NAME,
        "email": EMAIL,
        "is_email_verified": 1,
        "plans": [
          {
            "city_id": 2,
            "start_date": "2019-07-24",
            "end_date": "2019-07-28",
            "num_of_days": 5,
            "preferences": "landmarks,history,architecture,churches",
            "hotel_latitude": 34.85,
            "hotel_longitude": 32.288888,
            "user_type": 1,
            "city_name": "Tel Aviv"
          },
          {
            "city_id": 1,
            "start_date": "2019-09-04",
            "end_date": "2019-09-08",
            "num_of_days": 5,
            "preferences": "landmarks,history,art,architecture,churches",
            "hotel_latitude": 48.8888,
            "hotel_longitude": 2.27777,
            "user_type": 1,
            "city_name": "Paris"
          }
        ]
      }
    }
    Returns user details + plan info for each city that the user has an itinerary for
    * Update user details
    Action: Update user details (except password).
    URL: https://trip.expert/api/user/update
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,            //mandatory. INTEGER.
        'first_name': '...',           //optional. STRING.
        'last_name': '...',            //optional. STRING.
        'email': '...',                //optional. STRING.
        'is_email_verified': 1         //optional. INTEGER. Can be 0-no / 1-yes
    }
    Response
    {
        "status":1,
        "msg":"User details were update successfully."
    }
    To change user's password, use /api/user/password
    * Update user password
    Action: Update user password.
    URL: https://trip.expert/api/user/password
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,             //mandatory. INTEGER.
        'password': '...',              //mandatory. STRING. MD5(). 32 characters length.
    }
    Response
    {
        "status":1,
        "msg":"User details were update successfully."
    }
    USER_ID must be "owned" by the partner. Password must be MD5() encrypted.

    Plan and Itinerary API

    * Create a new plan
    Action: Create a new plan.
    URL: https://trip.expert/api/plan/create
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,                                 //mandatory. INTEGER.
        'city_id': CITY_ID,                                 //mandatory. INTEGER.
        'start_date': '2019-09-04',                         //mandatory. STRING. YYYY-MM-DD.
        'end_date': '2019-09-08',                           //mandatory. STRING. YYYY-MM-DD.
        'user_type': 1,                                     //optional. INTEGER.
        'preferences': 'landmarks,history,architecture',    //optional. STRING.
        'hotel_latitude': '.....',                          //optional. FLOAT. But hotel cannot be too far from the city.
        'hotel_longitude': '.....'                          //optional. FLOAT.
    }
    Returns plan details and new itinerary according to the up-to-date plan details.
    * Get plan details
    Action: Get plan details and its city itinerary.
    URL: https://trip.expert/api/plan/details
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,         //mandatory. INTEGER.
        'city_id': CITY_ID          //mandatory. INTEGER.
    }
    * Update plan details
    Action: Update plan details and replan the itinerary according to new plan details.
    URL: https://trip.expert/api/plan/update
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,                                 //mandatory. INTEGER.
        'city_id': CITY_ID,                                 //mandatory. INTEGER.
        'start_date': '2019-09-04',                         //mandatory. STRING. YYYY-MM-DD.
        'end_date': '2019-09-08',                           //mandatory. STRING. YYYY-MM-DD.
        'preferences': 'landmarks,history,architecture',    //optional. STRING.
        'user_type': 1,                                     //optional. INTEGER.
        'hotel_latitude': '.....',                          //optional. FLOAT. But hotel cannot be too far from the city.
        'hotel_longitude': '.....'                          //optional. FLOAT.
    }
    Returns plan details and itinerary.
    * Replan itinerary
    Action: Replan the city itinerary for specific plan.
    URL: https://trip.expert/api/plan/replan
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,           //mandatory. INTEGER.
        'city_id': CITY_ID            //mandatory. INTEGER.
    }
    May be useful if itinerary was updated long ago and you expect replanning will generate a more up-to-date itinerary.
    * Delete a plan
    Action: Delete entire info about the city for the specific user. The city plan and its itinerary.
    URL: https://trip.expert/api/plan/delete
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,           //mandatory. INTEGER.
        'city_id': CITY_ID            //mandatory. INTEGER.
    }
    * Export a plan to PDF file
    Action: Export city plan and itinerary to PDF file.
    URL: https://trip.expert/api/plan/export
    Request
    {
        'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
        'user_id': USER_ID,           //mandatory. INTEGER.
        'city_id': CITY_ID            //mandatory. INTEGER.
    }
    A link to the PDF file is returned. The file should be fetched asap. It will be removed from server after a few hours.

    Around API (coming soon)

    * Get sights around user's current location
    Action:
    URL: https://trip.expert/api/around/sights
    Request
    
             
            
    	
    * Get food places around user's current location
    Action:
    URL: https://trip.expert/api/around/food
    Request
    
             
            
    	
    * Get shopping places around user's current location
    Action:
    URL: https://trip.expert/api/around/shopping
    Request
    
             
            
    	
    * Get all kind of places around user's current location
    Action:
    URL: https://trip.expert/api/around/all
    Request
    
             
            
    	

    Partner API (coming soon)

    * Get partner statistic
    Action:
    URL: https://trip.expert/api/partner/statistics
    Request
    
             
            
    	
    * Get partner's activity log
    Action:
    URL: https://trip.expert/api/partner/log
    Request
    
             
            
    	


    Some More Info



    status


    API responses always return with status which can be either 0 or 1.
    0:failure, 1:success

    city_id


    1:Paris, 2:Tel Aviv

    preferences


    Comma-separated list.
    Landmarks, History, Culture, Art, Architecture, Churches, Science, Hidden gems, Kids, Outdoor, Food, Shopping, Nightlife, Out of town, Beaches, Pride.
    This field is optional.
    The default is: Landmarks,History,Culture,Art,Architecture,Hidden gems,Food,Shopping
    Note: The list is not necessarily the same for all cities. E.g. some cities do not have beaches.
    Get the city preferences by calling /api/city/info.

    user_type


    You may define the user type, if you know it, for better planning.
    1:Couple,2:Family with young kids,3:Family with teenagers,4:Solo traveler,5:Business traveler
    This field is optional. The default is 1.

    password


    No need to send password for the user.
    A password will be generated automatically upon account creation and will be sent to the user.
    The user may change the password later on.