Знакомство с Semantic3 API

В этом небольшом посте описывается работа с сервисом Semantics3, с которым я познакомился в процессе разработки некого портала для покупок в интернете.
Цель сервиса — собрать в одном месте все товары в мире и давать доступ магазинам по API к своей базе, где можно будет видеть динамику цен, кто что продает и так далее(на данный момент проиндексировано более 35 миллионов продуктов). После того, как Google Search API for Shopping “ушел на пенсию”, Semantics3 стремительно набирает обороты. Входит в семерку лучших стартапов в фонде Y Combinator за зимнюю сессию 2013 года.

Начало работы

В первую очередь необходимо зарегистрировать аккаунт у них на сайте, чтобы получить ключ для использования API. Затем можно выбрать любой из 4 тарифных планов. Я же залогинился через GitHub аккаунт — получил API key и API secret, и выбрал бесплатный план, с ограничением 1000 запросов в день.

API-запрос состоит из 3 компонентов:
К примеру URL:
(https://api.semantics3.com/v1 — API Endpoint
/products? — Resource
q={«cat_id»:13658,«brand»:«Toshiba»,«model»:«Satellite»}) — Query Parameters

API Endpoint — это версия сервиса для использования. Делится на Production(https://api.semantics3.com/v1) и Test/Development(https://api.semantics3.com/test/v1). Отличается по способу аутентификации и ограничением по количеству вызовов API в день. Для Test это базовая аутентификация(возможность использования Curl) и ограничение 100 вызов/день). Для Production используется OAuth v1.0 2 аутентификация и ограничение в зависимости от выбранного тарифного плана.

Resource — API можно использовать для получения продуктов(/products) и категорий(/categories).Все продукты организованны по категориям(cat_id), которые имею древовидную структуру-
К примеру существует категория «Electronics»(cat_id 13658), которая содержит несколько дочерних категорий, включая «Computers & Accessories»(cat_id 4992), которая в свою очередь включает в себя дочерную категорию «Scanners» (cat_id 14047).

Query Parameters — поисковые запросы выражаются в виде строки JSON. Можно построить очень гибкие запросы, используя до 50 различных полей.

API Libraries

В процессе разработки, во время тестирования поисковых запросов, можно использовать утилиту Curl.

 curl -G -H "api_key: SEM3E892B8487C7EA8267E1B0C8CE8345157" https://api.semantics3.com/test/v1/products --data-urlencode 'q={"cat_id":13658,"brand":"Toshiba","model":"Satellite"}' 

Вообще же Sematic3 выпустил несколько библиотек для доступа к Production API-
реализации на Perl, Python, PHP, Node.js, Ruby, Java и C#.
Вот пример использования гема semantics3 в Ruby:

      require 'rubygems'       require 'semantics3'        API_KEY = 'SEM3xxxxxxxxxxxxxxxxxx'       API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxx'       sem3 = Semantics3::Products.new(API_KEY,API_SECRET)        sem3.products_field( "cat_id", 4992 )       sem3.products_field( "brand", "Toshiba" )       productsHash = sem3.get_products       puts "Results of query:\n",productsHash.to_json 

Что вернет список из 10 первых продуктов бренда “Toshiba” из категории “Netbooks”. Список представлен в формате JSON, для каждого продукта имеются поля “name”, “price”, “img”(недоступен для тарифного плана basic), “url”(адрес сайта поставщика) и т. п. Это можно отобразить в виде веб-страницы с перечнем продуктов.

Примеры поисковых запросов можно посмотреть в документации.

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