travel.izi.api.service.SearchService Maven / Gradle / Ivy

Go to download
/*
 * Copyright (C) 2014 IZITEQ B.V.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package travel.izi.api.service;

import retrofit.http.GET;
import retrofit.http.Query;
import travel.izi.api.model.entity.CompactMtgObject;
import travel.izi.api.model.entity.FullMtgObject;

import java.util.List;

/**
 * Endpoints for Search.
 */
@SuppressWarnings("unused")
public interface SearchService {

    /**
     * Search all over IZI.directory content. Supports full-text search, area search,
     * transparent sorting and pagination.
     * Examples:
     * 

     * 
     * Find all cities which have content on English language and sort them by name.
     *      * /mtg/objects/search?languages=en&type=city&sort_by=title
     * 
     * 
     * 
     * Find all tours, cities and countries which have content on English and Dutch and also have `ams` in their title.
     *      * /mtg/objects/search?languages=en,nl&type=city,country,tour&query=ams
     * 
     * 
     * 
     * Find all countries which have content on Russian and sort them alpabetically.
     *      * /mtg/objects/search?languages=ru&type=country&sort_by=title
     * 
     * 
     * 
     * Find all tours with English language, do not include publisher section to results Compact MtgObjects, but include city section.
     *      * /mtg/objects/search?languages=en&type=tour&includes=city&except=publisher
     * 
     * 
     * 
     *
     * @param languages  Array of languages which should have MtgObject.
     * @param includes   Array of {@link travel.izi.api.service.constant.ContentSectionModifier} which should be included into MtgObject.
     * @param except     Array of {@link travel.izi.api.service.constant.ContentSectionModifier} which should NOT be included into MtgObject.
     * @param types      Array of requested {@link travel.izi.api.model.enumeration.MtgObjectType}, defaults are `tour`, `museum`.
     * @param query      Query for full-text search.
     * @param region     UUID of the city or country, limits search by city or country with provided UUID.
     * @param lat_lon    Geo location used to sort found MtgObjects from provided point, defaults to 0.0,0.0.
     * @param radius     Radius in meters, used only with #lat_lon param to search MtgObjects in area.
     * @param ex_lat_lon Geo location, used only with #ex_radius to exclude from area search certain area.
     * @param ex_radius  Radius in meters, used only with #ex_lat_lon to exclude from area search certain area.
     * @param sort_by    Sorting field in format 'field:direction', currently possible values are `popularity` and `title`.
     *                   Default sort order for popularity is desc, whereas default sort order for title is asc.
     *                   Example, "...&sort_by=title:asc&...". If results keeps `city` or `country` objects in additional
     *                   to `museum`, `tour`, etc, `country` objects will be returned first, next `city` objects and finally
     *                   rest of objects. Each set will be sorted according to `sort_by` criteria.
     * @param cost       Filtering content by {@link travel.izi.api.service.constant.Cost}, by default filter is not applied.
     * @param limit      Limit, defaults to 50.
     * @param offset     Offset, defaults to 0.
     * @return List of various MtgObjects(Museum, Tour, City, Country, etc).
     * @see #searchFull(String[], String[], String[], String[], String, String, String, Integer, String, Integer, String, String, Long, Long, Boolean)
     */
    @GET("/mtg/objects/search?form=compact")
    List searchCompact(
            @Query("languages") String[] languages,
            @Query("includes") String[] includes,
            @Query("except") String[] except,
            @Query("type") String[] types,
            @Query("query") String query,
            @Query("region") String region,
            @Query("lat_lon") String lat_lon,
            @Query("radius") Integer radius,
            @Query("ex_lat_lon") String ex_lat_lon,
            @Query("ex_radius") Integer ex_radius,
            @Query("sort_by") String sort_by,
            @Query("cost") String cost,
            @Query("limit") Long limit,
            @Query("offset") Long offset
    );

    /**
     * Search all over IZI.directory content. Supports full-text search, area search,
     * transparent sorting and pagination.
     *
     * @see #searchCompact(String[], String[], String[], String[], String, String, String, Integer, String, Integer, String, String, Long, Long)
     */
    @GET("/mtg/objects/search?form=full")
    List searchFull(
            @Query("languages") String[] languages,
            @Query("includes") String[] includes,
            @Query("except") String[] except,
            @Query("type") String[] types,
            @Query("query") String query,
            @Query("region") String region,
            @Query("lat_lon") String lat_lon,
            @Query("radius") Integer radius,
            @Query("ex_lat_lon") String ex_lat_lon,
            @Query("ex_radius") Integer ex_radius,
            @Query("sort_by") String sort_by,
            @Query("cost") String cost,
            @Query("limit") Long limit,
            @Query("offset") Long offset,
            @Query("children_count_in_full_form") Boolean children_count
    );

}