API

// TODO Характеристики объекта. Линия домов – поле с возможностью выбора значений выпадающего списка
// TODO Дополнить типы ошибок 
  
/*
enum - передаются в виде строки ("INTERNAL" для ErrorType::INTERNAL)
type - передаются в виде json
    например для {user User, error Error} может быть передано:
        {
            "user" : {
                type : "EXPERT"
            }
        }
    если ошибка отсутствует, просто не передавать ее и т.д.
func - все запросы и ответы передаются через POST в виде json, Content-Type: application/json
по адресу /rest/getFilterOffers для функции getFilterOffers()
  
Для фильтров какие-то параметры могут отсутствовать,
соответственно их нужно просто игнорировать при фильтрации
 
Типы данных в фронте и беке могут несколько различаться, однако картина остается общей для обеих сторон. Для каждой сущности описанной ниже и имеющей различия в типах данных с тем, что написано тут, в скобках будет указано имя класса, которое можно посмотреть в Java проекте.
 */
  
enum Currency { //Валюта
RUB //Рубли
USD //Доллары
EUR //Евро
}
 
enum ErrorType {
    BAD_TOKEN // невалидный токен пользователя.
    INTERNAL //внутренняя ошибка
}
 enum MarketType {
SALE, //Продажа
RENT //Аренда
}
 
 enum OfferType {
    FLAT        // жилая недвижимость
    COMMERCIAL  // коммерческая недвижимость   
}
enum RealtyType {
    RESALE // Квартира
    NEWBUILDING // Новостройки
    LAND //Участок
    HOUSE //Дом
    DACHA //Дача
    TOWNHOUSE //Таунхаус
    CHALLET //Коттедж
    OFFICE_COMMERCIAL //Офисные помещения
    TRADE_COMMERCIAL //Торговые помещения
    WAREHOUSE_COMMERCIAL //Производственно складские помещения
    FREE_COMMERCIAL //Помещения свободного назначения
    BUILDING_COMMERCIAL //Отдельно стоящие здания
    LAND_COMMERCIAL // Земельный участок (коммерческий)
    OTHER_COMMERCIAL // Другое (коммерция)
 }
enum EntryType {
    BY_PASS     // по пропуску
    SEPARATE    // отдельный вход
    FREE        // свободный вход
}
enum BuildingType {
    RESIDENTIAL     // жилое
    NON_RESIDENTIAL // нежилое
}
enum BuildingClass {
    A
    APLUS
    B
    BPLUS
    C
    CPLUS
    D
    DPLUS
}
enum ContractType {
    SALE            // продажа
    PERMISSION      // переуступка прав
    DIRECT_RENT     // прямая аренда
    SUB_RENT        // субаренда
}
enum WallsType  {
    PANEL               // панельный
    KIRPICH                 // кирпичный
    WOODEN              // деревянный
    MONOLITH            // монолитный
    BLOCK               // блочный
    MONOLITH_KIRPICH    // монолитно-кирпичный 
}
enum FigureType {
    BOX
    CIRCLE
}
type Figure (Figure.java) {
    type    FigureType
}
type Box extend Figure {
    box [2][2]float
}
type Circle extend Figure {
    center  [2]float
    radius  float
}
type date string // в формате ISO: "2016-07-27"
 
type Error {
    type ErrorType
    msg string      // Текст для пользователя, не обязательно, но желательно, если есть что сказать.
}
 
// для каждой выгрузки отчета создавать свой объект контекста,
// в котором хранится контекст поиска аналогов
type Context (ReportContext.java) {
    reportId            string      // id отчета
    favoriteIDs []string    // id избранных объектов
    environment json        // json с состоянием среды (приближение карты, фильтры и т.д.)
    reportLink  string      // адрес страницы отчета, для которого производиться поиск аналогов
    modified    date        // время последнего изменения контекста
    created     date        // время создания объекта контекста
    comparable  ComparableOffer // информация об объекте, для которого ищутся аналоги
}
 
type Offer (Offer.java) {
    id              string
    type            OfferType
    realtyType      RealtyType
    title           string      //Заголовок объявления
     url           string      // Исходная ссылка на исходное объявление аналога
    photoUrls       []string    // Ссылки на фотографии аналога
    rawAddress      string      // Адрес объекта (склеенная строка субъект, населенный пункт улица и т.д.)
    location        [2]double   // координаты объекта если есть.
    date            date        // дата объявления
    markNoticed     date        // дата, когда объявление было замечено на сайте последний раз.
    sourceName      string      // источник объявления, оригинальное имя из базы в виде 'cian.ru'
    sourceText      string      // источник объявления в красивом представлении. В формате 'ЦИАН'
    currency        Currency //Валюта объявления
    price           long        // цена
    pricePerMeter   long        // цена за метр
   trusted         bool        // проверен объект или нет.
    floor           integer     // этаж
    rooms           integer     //количество комнат
       space           double      // Общая площадь
    storeys         []integer // Количество этажей, либо фиксированно [4] либо диапозон 5-9: [5,9]
    text            string      // Текст объявления на сайте
   //bounds           [2][2]double // [["37.60231,55.750256],[37.618767,55.759537]] левый нижний правый верхний угол
}
 
type OfferCommercial extend Offer {
    entryType       EntryType
    buildingType    BuildingType    
    buildingClass   BuildingClass   // например APLUS
    furniture       bool            // есть ли мебель
    contractType    ContractType
    line            int             // линия домов
  
    floor           int
    pricePerMeter   long
    rooms           int
 }
type OfferFlat  extend Offer {
    houseType string //Тип дома
    wallsType WallsType //Тип стен
    living      float   // жилая площадь
    kitchen float   // площадь кухни
}
// Объект, для которого ищутся аналоги
type ComparableOffer extend Offer {
}
  
type Filter (Filter.java) {
    type            []OfferType
    realtyType      []RealtyType
    marketType      []MarketType
     price     {
        from    uint
        to      uint
    }
    photoRequired   bool
    date    {
        from    date
        to      date
    }
    markNoticed { //Когда объявление было замечено на сайте последний раз (от- до)
        from    date
        to      date
    }
    location    []Figure
    sources     []string // список сайтов источников, в формате cian.ru, если пустой, то искать по всем.
    currency Currency //Валюта объявления
     space {       // общая площадь
        from    float
        to      float
    }
    customQueryLimit uint //Лимит на количество возвращаемых объектов
}
type FilterCommercial extend Filter {
    entryType   []EntryType // если ничего не указано, то искать по всем
    floor   {
        from        uint
        to          uint
    }
    floorHint   {
        notFirst    bool
        notLast     bool
    }
    storeys { // количество этажей
        from        uint
        to          uint
    }
    buildingType    []BuildingType
    buildingClass   []BuildingClass
    furniture       bool    // наличие мебели - true/false/undefined есть/нет/не важно
    rooms   {   // количество комнат
        from    uint
        to      uint
    }
    pricePerMeter   {
        from    uint
        to      uint
    }
    contractType    []ContractType
    line            []uint          // линии домов
    //include       []string    // включить слова
    //exclude       []string    // исключить слова
}
type FilterFlat extend Filter {
    floor   {   // этаж
        from        uint
        to          uint
    }
    floorHint   {
        notFirst    bool
        notLast     bool
    }
    storeys { // количество этажей
        from        uint
        to          uint
    }
    wallsType   []WallsType
    rooms       []uint  // формат [2,3,4] если есть 4 то искать 4+, если массив пустой, то игнорировать
    livingSpace {
        from    float
        to      float
    }
    kitchenSpace    {
        from    float
        to      float
    }
    pricePerMeter   {
        from    uint
        to      uint
    }
}
type Token { // JWT token
    id  string
    ...
}
 
Новые классы на замену Offer и OfferCommercial
 
GeoPoint
double lat;//Широта
double lon;//Долгота
 
JsonOffer
/**Идентефикатор (пока никак не используется) */
 Long id;
 
/** Идентефикатор записи в MongoDB (используется в запросах в качестве идентефикатора) */
 String mongoId;
 
/** Заголовок объявления на сайте */
 String title;
 
/** Идентефикатор города */
 Integer cityId;
 
/** Идентефикатор улицы */
 Integer streetId;
 
/** Адрес объявления, как указано на сайте */
 String rawAddress;
 
/** Номер дома */
 String houseNumber;
 
/** Количество комнат */
 String rooms;
 
/** Общая площадь */
 Double total;
 
/** Площадь кухни */
 Double kitchen;
 
/** Жилая площадь */
 Double living;
 
/** Санузел */
 String bathroom;
 
/** Балкон */
 String balcony;
 
/** Ремонт */
 String repairs;
 
/** Этаж */
 Integer floor;
 
/** Является ли здание новостройкой */
 Boolean newBuilding;
 
/** Материал стен */
 String walls;
 
/** Этажность здания */
 Integer storeys;
 
/** Год постройки */
 Integer built;
 
/** Планировка */
 String plan;
 
/** Валюта объявления */
 String currency;
 
/** Цена */
 Long price;
 
/** Цена за квадратный метр */
 Long pricePerMeter;
 
/** Дата публикации объявления */
 Date published;
 
/** Дата, когда объявление было замечено на сайте последний раз */
 Date markNoticed;
 
/** Текст объявления с описанием */
 String info;
 
/** Детали контактов */
 String contactDetails;
 
/** Ссылка на объявление */
 String url;
 
/** Статус местоположения */
 String status;
 
/** Дата последнего обновления объявления */
 Date lastUpdate;
 
/** Идентефикатор ориентира */
 Integer referenceId;
 
/** Гео-локация объекта (не используется в сервисе) */
 GeoData geoData;
 
/** Гео-локация объекта */
GeoPoint location;
 
 /** Идентефикатор района */
 Integer districtId;
 
/** Ссылки на фотографии объявления */
 String[] photoUrls;
 
/** Тип недвижимости (квартира, новостройка, офисное помещение и т.д.) */
 String realtyType;
 
/** Источник объявления (циан, домофонт и т.д.) */
 String sourceName;
 
/** Тип сделки (переуступка прав аренды, полная продажа и т.д.) */
 String contractType;
 
JsonCommercialOffer extends JsonOffer
/** Тип сделки (продажа/аренда) */
private String marketType;
 
/** Тип здания (жилое/ нежилое) */
private String buildingType;
 
/** Класс здания (А, А+, B и т.д.) */
private String buildingClass;
 
/** Пропускная система */
private String controlSystem;
 
/** Интернет */
private String internet;
 
/** Наличие мебели */
private Boolean furniture;
 
/** Телефонная линия */
private String phoneLine;
 
/** Тип входа (по пропуску, свободный вход, отдельный вход) */
private String entryType;
 
/** Линия домов */
private Integer line;
 
 
 //Получить список источников объявлений жилой недвижимости
func getFlatSources({token Token}) {sources[] String, error Error}
 
//Получить список источников объявления коммерческой недвижимости
func getCommercialSources({token Token}) {sources[] String, error Error}
 
 //Получить список типов объектов недвижимости жилой недвижимости (вторичка, новостройка и т.д.)
func getFlatRealtyTypes({token Token}) {realtyTypes[] String, error Error}
 
 //Получить список типов объектов недвижимости коммерческой недвижимости (офис, склад и т.д.)
func getCommercialRealtyTypes({token Token}) {realtyTypes[] String, error Error}
 
  // Получить объект контекста по token
func getContext({token Token}) {context Context, error Error}
 
// Получить список объектов
// если объект не найден, просто пропустить
func getOffers({token Token, offerIDs []string, short bool}) {offers []Offer, error Error}
  
// Отфильтровать объекты по фильтру
func filterOffers({token Token, filter Filter}) {offers:{id, location, realtyType}, error Error}
  
// Обновить контекст
// поля могут не все передаваться,
// соответственно обновлять только переданные
func updateContext({token Token, context Context}) {error Error}
  
// Добавить объект в отчет
// по socket.io отправить в заблокированную таблицу на странице отчета.
func addOfferToReport({token string, offerID string}) {error Error}
 
// Запрос в yandex maps
// result - json, который вернет yandex
func ymaps({token string, query string}) {result json, error Error}
 
// Получить список избранного по всем контекстам
//func getAllFavorites({tokens []Token}) {favoriteIDs []string, error Error}
 
// Получить все контексты у пользователя
//func getUserContexts({tokens []Token}) {contexts []ContextShort, error Error}
 
// Удалить объект контекста
//func deleteContext({token Token}) {error Error}
 
// Создать xls файл списка объектов и вернуть ссылку на него.
// func generateXls({token string}) {link string, error Error} видимо не нужно