API Documentation | Trip.Expert

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 partner 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, user preferences full list 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: 'support@trip.expert',
    guides: {
        food: [...]
        nearby: [...]
        shopping: [...]
        sights: [...]
    },
    list_of_preferences: 'Landmarks, History, Culture, Art, Architecture, Churches, Science, Hidden gems, Kids, Outdoors, 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

{
    status: 1,
    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.
If hotel's location is not set, it will be defined as the default city center.

* 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.

Helper API

* Get place info by address

Action: Get coordinates of an address. Usually used to get the hotel's location from its address.
URL: https://trip.expert/api/helper/get_basic_place_info_by_address
Request

{
    'partner': {'api_key': API_KEY, 'api_secret': API_SECRET},
    'city_id': CITY_ID                  //mandatory. INTEGER.
    'address': ADDRESS_IN_FREE_FORMAT   //mandatory. INTEGER.
}

Response

{
	'status': 1,
	'lat': LATITUDE,
	'lng': LONGITUDE,
	'distance_from_city_center': DISTANCE_IN_METERS
}

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, Outdoors, 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.