{
   продукт: "информация", // передача в формате JSON
   удобно: да, // через простой и понятный интерфейс
   быстро: да, // без каких-либо ограничений
   доступно: да // за символическую плату
}

документация версия 1.0.0

  • основные положения
  • формат полей
  • мультиязычность
  • типы данных
  • системные параметры запроса
  • фильтрация по полям
  • авторизация в интерфейсе
  • завершение сеанса
  • скроллинг данных
  • пример полноценного запроса к интерфейсу, включая скроллинг
  • основные положения

    Интерфейс работает через HTTP протокол с данными в формате JSON. Метод запроса и путь у каждого пакета услуг индивидуален и находится в его описании. Это выглядит примерно так:

    POST https://api.getyourbit.com/action/:param/

    В примере выше видно, что необходимо использовать метод POST, а также возможность отправки дополнительного параметра в url. Описание всех передаваемых параметров, как в пути, так и в теле запроса, можно найти на странице пакета.

    В случаи успеха вы получите в ответе объект { "data": ...данные, ...прочие системные свойства }

    Если же на сервере произойдет ошибка, то { "error": true, "message": "сообщение об ошибке", ...прочие уточняющие метаданные }, а также соответстующий http-код ответа, отличный от 200.

    Параметры запроса можно разделить на индивидуальные и системные. К первой группе относятся те, что разнятся в пакетах. Во второй же такие, которые непосредственно являются частью нашего api-интерфейса, отвечают за какие-либо настройки или шаблонное поведение. Они обозначаются значком

    Иконки, характеризующие особенности параметров запроса:
    • - системное поле
    • - может быть несколько значений в массиве
    • - мультиязычное поле, можно отправлять и получать данные на разных языках
    • - в данном поле можно вести поиск по совпадению фразы
    • - в данном поле можно вести поиск по полному совпадению
    • - в данном поле можно вести поиск в диапазоне
    • - в данном поле можно вести поиск по cовпадению с элементами массива
    • - в данном поле можно вести поиск по географической близости
  • формат полей

    Параметры можно записывать и получать в нескольких вариантах:
    • "camel" => "someField"
    • "pascal" => "SomeField"
    • "underscore" => "some_field"
    • "dash" => "some-field"

    Отправлять данные вы можете в любом из перечисленных вариантов, например, можно составить такой запрос:

    { 
      "locale": "en",
      "strong-fields": true,
      "strongLocale": false
    }

    Если же вы хотите получать данные в каком-то определенном виде, то во время запроса нужно указать параметр case, например, { "case": "underscore" }.

    Форматом получения по умолчанию является "camel".

  • мультиязычность

    Поля, рядом с которыми есть иконка , могут содержать значения на разных языках. Список поддерживаемых языков находится в описании пакета услуг.

    Отправлять данные в таких полях можно на любом из поддерживаемых языков, но для получения в нужном, необходимо при передаче указать параметр locale, например, { "locale": "en-US" }.

    Значение локали может быть записано как "en-US", "en", "en_US", "en-us" или в виде объекта { "language": "en", country: "US" }.

    Если какой-то язык присутствует в поддерживаемых, это не гарантирует наличие значений на данном языке в каждом мультиязычном поле. Может случится, что у какого-то отдельного поля не будет нужного перевода, тогда вы получите значение на языке по умолчанию, либо пустое значение, если { "strongLocale": true }.

  • типы данных

    Наш интерфейс поддерживает следующие типы данных:
    • boolean - логический тип, может быть true или false.
    • integer - целое число, например, 279.
    • float - дробное число, например, 270.99.
    • string - строка, например, "antonio".
    • datetime - дата и время. Для запросов необходимо использовать один из двух вариантов: UNIX-время в миллисекундах, либо дату в формате ISO 8601, например, 1087712521, "2004-06-20T06:01Z" и.т.д. Ответ же от сервера будет в формате, указанном в параметре запроса dateFormat, по умолчанию это UNIX-время в миллисекундах.
    • geopoint - географические координаты, передаются в массиве как долгота и широта, например [37, 55].
  • системные параметры запроса

    • token string уникальный хэш активной сессии для подтверждения доступа, выдается при авторизации. Передавать нужно каждый запрос.
    • locale string|object локаль в формате ISO, например, "en", "en-US", "en_US" или объект { "language": "en", "country": "US" }. От этого поля зависит на каком языке вы получите данные. Если его проигнорировать, то язык будет выбран автоматически, исходя из вашего запроса. При невозможности этого, значение проставится по умолчанию. Регистр значения не имеет. по умолчанию: "en"
    • dateFormat string формат получения даты и времени. По умолчанию или если передана пустая строка, в ответе возвращается UNIX-время в миллисекундах, но вы можете указать свой формат. Он записывается в стиле функции strftime на многих языках программирования, например, "%d/%m/%Y %H:%M:%S" => "01/01/1970 12:34:56"
    • case string формат ключей получаемых данных. Например, "camel" вернет ключ в виде "someField", "underscore" => "some_field". по умолчанию: "camel"
    • strongLocale boolean если true, то все переводимые строковые данные вы получите на нужном вам языке, либо они будут пустые, если на выбранном языке отсутствуют. Если же false, то даже в случаи отcутствия, вы получите данные, но на языке локали по умолчанию. по умолчанию: false
    • strongFields boolean если true, то в ответе будут только те поля, которые содержат хоть какое-то значение, если false, то вы получите все ключи, даже если у них пустые значения. по умолчанию: true
    • fields string можно в ручную указать какие поля получить в ответе. Например, ["field1", "field2"].
    • scroll string в режиме скроллинга вы получаете данные по кускам, данный параметр представляет собой хэш-строку, которая выдается в каждом запросе, кроме последнего, когда данные уже закончатся. Каждый новый запрос, после первого, вы должны использовать уже не различные фильтры и уточнения, а посланное значение поля scroll, чтобы получить следующую порцию данных.
    • size integer количество элементов, которое вы хотите получить в каждом наборе данных в режиме скроллинга. Имейте ввиду, на сервере могут быть ограничения по максимальному значению. по умолчанию: 100
    • query object|array схема фильтрации данных по полям. Может быть объектом-фильтром, либо массивом объектов-фильтров. Ключи объекта-фильтра работают по типу "И", требуют полного соответствия каждому условию. Передача же массива объектов-фильтров подразумевает операцию "ИЛИ", то есть условие будет удовлетворено, если хотя бы один из объектов-фильтров в массиве проходит проверку. Например, объект-фильтр { "age": 5, "name": "Петя" } вернет данные где оба поля совпадают с условием. А схема [ { "age": 5, "name": "Петя" }, { "name": "Катя" } ] вернет данные удовлетворяющие хотя бы одному объекту-фильтру массива.
  • фильтрация по полям

    Как вы могли заметить выше, фильтрация данных по полям происходит при помощи параметра query в теле запроса, и все условия помещаются в него { "query": ...условия }. Он может быть как объектом-фильтром, так и массивом таких объектов. Предположим, что мы работаем с неким интерфейсом, поддерживающим фильтрацию данных, который должен нам возвращать информацию о людях. Варианты фильтрации:

    • - фильтрация по точному совпадению. Например, { "age": { "is": 27 } } выберет всех людей, которым 27 лет.

      Обратите внимание, код выше можно написать и как { "age": 27 }, при условии, что данное поле имеет в описании соответствующий значок, идущий первым, наример,

      Если is присутствует и находится в начале, это значит, что если не уточнять тип фильтрации данного поля, то по умолчанию будет соответствующее. Поэтому в данном случаи оба кода идентичны. Но если в описании было бы, например, , тогда { "age": 27 } было бы эквивалентно { "age": { "like": 27 } } .

    • - фильтрация по совпадению фразы. Например, { "name": { "like": "lex" } } выберет людей, у которых в имени присутствует "lex", без учета регистра: "Alexandr", "Alexey" и.т.д.

    • - фильтрация по совпадению с элементами массива. Например, { "age": { "in": [18, 25, 27] } } выберет всех людей, которым 18, 25 или 27 лет.

    • - фильтрация по диапазону значений. Например, { "age": { "gte": 18, "lte": 25 } } выберет всех людей, чей возраст составляет от 18 до 25 лет включительно. Ключ gt эквивалентен "больше (>)", gte - "больше или равно (>=)", lt - "меньше (<)", lte - "меньше или равно (<=)".

    • - фильтрация по георграфической близости. Например, { "location": { "near": [85, 27], "distance": 100 } } найдет всех людей, которые находятся в радиусе 100км от указанных координат. Если не указать distance, то подставится значение по умолчанию.

    В примере ниже показано как выглядит объект-фильтр query. Общее условие будет выполнено, если все вложенные условия будут верны. То есть будут найдены люди с черными волосами, именем "Peter" , находящиеся по указанным координатам.

    { 
      "query": { 
        "location": {
          near: [85, 27]  
        }, 
        "name": "Piter",
        "hairColor": "black"
      } 
    }

    Если query написать как массив, то его элементами должны быть объекты-фильтры, как в первом примере. При этом для удовлетворения общего условия, достаточно, чтобы сработал любой из них.

    { 
      "query": [ 
        { 
          "location": {
            "near": [85, 27]  
          }
        },
        { 
          "name": "Piter",
          "hairColor": "black"
        } 
      ] 
    }

    Выше сформировано условие фильтрации, которое сработает, если человек находится по указанным координатам, либо его зовут "Peter" и он с черными волосами.

    Для того, чтобы в ответе получить только определенные поля, например, только "age" и "birthday", а не все сразу, вам необходимо добавить в запрос { "fields": ["age", "birthday"] }.

    Для того, чтобы отсечь в данных ответа все пустые поля, используйте { "strongFields": false }

  • авторизация в интерфейсе

    Прежде чем запросить какие-либо данные необходимо авторизоваться в системе, используя базовую аутентификацию. Данные для авторизации генерируются после того как вы совершаете подписку на какой-то пакет. Вы сможете найти их после этого в вашем профиле, в разделе подписок. Там будут указаны логин и пароль для каждой отдельной подписки.

    Вот как на разных языках программирования будет выглядеть авторизация:

    
    const GetYourBit = require('getyourbit');
    const api = new GetYourBit.Api('https://api.getyourbit.com');
    
    // авторизация
    api.auth('login', 'password').then((token) => {
      console.log(token);  
    });
    require 'vendor/autoload.php';    
    use GetYourBit\Api;
    
    $api = new Api('https://api.getyourbit.com');
    
    // авторизация
    $token = $api->auth('login', 'password');
    echo $token;
    from getyourbit import Api
    
    api = Api('https://api.getyourbit.com')
    
    # авторизация
    token = api.auth('login', 'password')
    print(token)

    После авторизации вы получаете специальный token - строку, которую нужно указывать при каждом последующем запросе на получение данных. Если вы используете одну из наших библиотек, то это будет происходит автоматически. Срок жизни сессии бесконечен, но в случаи 15 минут бездействия (отсутствия запросов), она будет автоматически завершена.

    Если вы уже авторизованы, то при повторной попытке никакой ошибки не произойдет.

  • завершение сеанса

    После того, как вы завершите все свои запросы желательно принудительно закрыть сессию:

    const GetYourBit = require('getyourbit');
    const api = new GetYourBit.Api('https://api.getyourbit.com');
    
    // авторизация
    api.auth('login', 'password').then(() => {
      // завершение сессии (не обязательно)
      return api.logout()
    });
    require 'vendor/autoload.php';    
    use GetYourBit\Api;
    
    $api = new Api('https://api.getyourbit.com');
    
    // авторизация
    $api->auth('login', 'password');
    // завершение сессии (не обязательно)
    $api->logout();
    from getyourbit import Api
    
    api = Api('https://api.getyourbit.com')
    
    # авторизация
    api.auth('login', 'password')
    # завершение сессии (не обязательно)
    api.logout()
  • скроллинг данных

    Некоторые запросы возвращают не один объект с данными, а массив { "data": [...данные] }. Интерфейсом ограничено максимальное количество элементов массива за один запрос. Такие запросы происходят со скроллином - получением всей информации частями, кусок за куском, с помощью специального параметра scroll.

    Если в ответе вы получили поле { "scroll": "hash" }, которое представляет из себя хэш-строку, значит для получения следующей порции данных вам нужно составить новый запрос с параметром scroll, значением которого будет полученный хэш. И так до тех пор, пока поле scroll в ответе не станет пустым.

    Вы можете самостоятельно указать размер порции данных, передав, например, параметр { "size": 200 }. Но помните, что каждый сервис имеет свой потолок по максимальному значению этого размера.

  • пример полноценного запроса к интерфейсу, включая скроллинг

    Допустим, как в примерах выше, мы работает с неким пакетом, который дает нам возможность получать массив данных о людях, с возможностью фильтрации по некоторым полям. Тогда код на различных языках программирования будет примерно такой:

    
    const GetYourBit = require('getyourbit');
    const api = new GetYourBit.Api('https://api.getyourbit.com');
    
    const data = {
      locale: "en",
      strongFields: false,  
      size: 200, 
      query: [
        {
          name: {
              like: 'onio'
          },
          age: {
              in: [18, 21]
          }
        },
        {
          age: {
              gt: 21
          }
        },
        {
          location: {
            near: [37, 55]
          },
          birthday: {
            lt: new Date("December 31, 2000 11:13:00")
          }
        }
      ]
    };
    
    // авторизация
    api.auth('login', 'password').then(() => {
      // получение данных  
      return api.scroll('/find/', data, (body, chunkData, fullData) => {
        // эта функция будет выполняться при получении каждой порции данных
        console.log(body, chunkData, fullData);
      });
    })
    .then((fullData) => {
      console.log(fullData); 
    
      // завершение сессии (не обязательно)
      return api.logout();
    })
    .catch((err) => {
      console.log(err);
    });
    require 'vendor/autoload.php';    
    use GetYourBit\Api;
    
    $api = new Api('https://api.getyourbit.com');
    
    $data = array(
        'size'=>200,
        'locale'=>'en',
        'strong_fields'=>false, 
        'query'=>array(            
            array(
                'name'=>array('like'=>'onio')
                'age'=>array('in'=>array(18, 21))
            ),
            array(
                'age'=>array('gt'=>21)
            )
            array(
                'location'=>array('near'=>array(37, 55)),
                'birthday'=>array('lt'=>strtotime("December 31, 2000 11:13:00") * 1000)
            )
        )
    );
    
    // авторизация
    $api->auth('login', 'password');
    
    // получение данных
    $fullData = $api->scroll("/find/", $data, function($body, $chunkData, $fullData) {
        // эта функция будет выполняться при получении каждой порции данных
        var_dump($body, $chunkData, $fullData);
    });
    var_dump($fullData);
    
    // завершение сессии (не обязательно)
    $api->logout();
    from getyourbit import Api
    
    api = Api('https://api.getyourbit.com')
    
    data = {
        'size': 200,
        'locale': u'en',
        'strong_fields': False, 
        'query': [
            {
                'name': {
                    'like': u'onio'
                },
                'age': {
                    'in': [18, 21]
                }
            },
            {
                'age': {
                    'gt': 21
                }
            },
            {
                'location': {
                    'near': [37, 55]
                },
                'birthday': {
                    'lt': time.mktime(datetime(2000, 12, 31, 11, 13).timetuple())
                }
            }
        ]
    }
    
    def on_chunk(body, chunkData, fullData):
        # эта функция будет выполняться при получении каждой порции данных
        print(body, chunkData, fullData)
    
    # авторизация
    api.auth('login', 'password')
    
    # получение данных   
    fullData = api.scroll('/find/', data, on_chunk)
    print(fullData)
    
    # завершение сессии (не обязательно) 
    api.logout()

    Наши библиотеки: