Datafeedr API, version 0.1b


The Datafeedr API is a programming interface for querying Datafeedr Product Database. To access the API you need an access id and a secret key.

Currently, the API only supports JSON as a request and response format, in the future we might add more formats.

Types

Following types are used in this documentation.

Basic types

string

A conventional JSON string. All strings sent to and returned by the API are UTF-8.

integer

A conventional JSON integer.

bool

A conventional JSON boolean (true or false). The API also accepts 1 and 0 respectively.

id

An usinged 64-bit integer used as an internal object id (e.g. a network id). The API accepts both numeric strings, like "123" or integers.

timestamp

A timestamp represents date and time as a string in the YYYY-MM-DD HH:MM:SS format. All timestamps sent to and returned by the API are UTC.

price

Prices are represented as integers, in least valued currency units, e.g cents.

arrays

The [type...] notation means "array of type objects", for example [Product...] is an array of Product objects.

Status Object

A JSON object describing the current API status and your account.

Property Value Type
network_count Total number of networks integer
product_count Total number of products integer
merchant_count Total number of merchants integer
plan_id Your Membership Plan ID string
bill_day Your billing day integer
request_count Number of requests made since the start of the billing period integer
max_total Max. number of total results allowed by your Membership Plan integer
max_length Max. number of per-request results allowed by your Membership Plan integer
max_requests Max. number of requests per billing period allowed by your Membership Plan integer

FieldType

A string, describes the type of the seach field. Currently supported field types are

Name Value
text A string, can be a subject for full-text search
int An integer
date A timestamp object

Field Object

A Field object contains the following properties:

Property Value Type
name Field name string
type Field type FieldType

Network Object

A JSON object describing the a single product network.

Property Value Type
id Network id id
name Network name string
group Network group name string
type Network type ("products" or "coupons") string
product_count Number of products from this network in the database integer
merchant_count Number of merchants from this network in the database integer

Merchant Object

A Merchant object has the following structure:

Property Value Type
id Merchant ID id
name Merchant name string
source_id Source (network) id id
source Source (network) name string
product_count Number of products from this merchant in the database integer

Product Object

A JSON object describing a single product. A ProductObject contains the following mandatory fields and a number of additional fields, depending on the network and merchant.

Mandatory fields are:

Property Value Type
id Product id id
name Product name string
source_id Source (network) id id
merchant_id Merchant id id
price Product price price
currency Three letter ISO-4217 currency code string
url Product "buy" URL. Contains the placeholder @@@ for the affiliate ID string
time_updated Timestamp of the last update timestamp

Most common additional fields:

Property Value Type
description Product description string
ref_url Product "referral" URL. Contains the placeholder ### for the referral ID string
image Image URL string
sale_price price
final_price price

MerchantCount object

Property Value Type
merchant Merchant name string
merchant_id Merchant ID id
product_count Count of products from this merchant in the results integer

SourceCount object

Property Value Type
source Source (network) name string
source_id Source (network) ID id
product_count Count of products from this network in the results integer

PriceGroup object

Property Value Type
min Minimal price in this group price
max Maximal price in this group price
count Product count in this group integer

Request

To access the API make a HTTP POST request to this address:

http://api.datafeedr.com/<action>

where <action> is one of the supported Api actions. The request JSON object should be provided in the request body.

The request must supply Content-type and Accept headers set to application/json.

A Request object must contain the following common properties and additionally action-specific properties:

Common Request properties

Property Value Type
aid your access id string
timestamp current date and time timestamp
signature request signature string

Response

If your request has been processed successfully, the API responds with the code 200 OK and a Response object. A Response object contains the following common properties and additionally action-specific properties:

Common Response properties

Property Value Type
version the API version string
time time spent processing your query (in milliseconds) integer
length number of items returned integer
status API status Status

Error Response

If you send a malformed or incorrect request, the API responds with an error code 400 Bad Request and returns an Error object:

Property Value Type
error error code integer
message error message string

Actions

status

Returns the API status.

Request properties

None

Response properties

No specific properties, only common response properties.

networks

Returns the list of networks.

Request properties

Property Value Type
source_ids (optional) List of network ids [id...]

Response properties

Property Value Type
networks List of networks [Network...]

merchants

Returns the list of merchants.

Request properties

Property Value Type
source_ids (optional) List of network ids [id...]

Response properties

Property Value Type
merchants List of merchant [Merchant...]

merchant_search

TODO

fields

Returns the list of product record fields.

Request properties

Property Value Type
source_ids (optional) List of network ids [id...]

Response properties

Property Value Type
fields Field descriptions [Field...]

search

Returns products matching the search query.

Request properties

Property Value Type
query Search query [string...]
sort (optional) Sort: a list of sort field names, each one preceded by + (=ascdening) or - (=descending) [string...]
fields (optional) Fields to return [string...]
limit (optional) Limit results integer
offset (optional) Offset integer
string_ids (optional) Encode product ids as strings bool
price_groups (optional) Number of price groups integer
exclude_duplicates (optional) Fields to exclude (TODO)

Response properties

Property Value Type
found_count Total number of products matching the query integer
result_count Number of products that can be retrieved from the server integer
merchants Per-merchant product counts [MerchantCount...]
networks Per-network product counts [SourceCount...]
price_groups (optional) Product counts, grouped by price [PriceGroup...]
products Found products [Product...]

If you provide the fields property in the Request, only the listed fields will be returned. When some product doesn't have the specific field, it may be omitted

If you don't provide fields, the Product object may contain other, merchant- and product-specific properties, all of type string.

The price_groups is only present in the response if price_groups is given in the request.

amazon_search

TODO

zanox_merchant_ids

TODO

Search query syntax

Each element of the query array represents a single condition. Conditions are AND'ed together, if you provide multiple elements, only products that match all of them will be returned. You can also include multiple conditions for the same field, for example a query:

["tags LIKE shoe", "price > 1000", "price < 2000"]

will select products tagged "shoe", with the price between 1000 and 2000 cents.

Conditions have the form

fieldName operator argument

where fieldName is either a field name or ANY (=any field). The meaning of the operator depends on the field type.

Operator is one of the following:

Operator Meaning Applies to FieldType Argument type
EMPTY field is empty text none, must be omitted
!EMPTY field is not empty text none, must be omitted
LIKE fulltext match text fulltext query
!LIKE fulltext not match text fulltext query
= strictly equal text, int, date string, integer, timestamp
!= strictly not equal text, int, date string, integer, timestamp
> more than integer, date integer, timestamp
>= more or equal integer, date integer, timestamp
< less than integer, date integer, timestamp
<= less or equal integer, date integer, timestamp
IN one of integer comma-separated list of ints
!IN neither of integer comma-separated list of ints

Examples of valid conditions:

name LIKE shoe
ANY !LIKE red
discount EMPTY
status = on sale
price > 10
merchant_id IN 123,456,789
time_updated >= 2011-12-14

Fulltext queries

consist of search words and, optionally, extended search operators:

Operator Meaning
"word word" exact phrase
=word exact word
!word exclude word
word | word any of words
^word start of field
word$ end of field

Examples of full-text conditions:

ANY LIKE shoe
name LIKE ^Red =shoe for (walking|running)
description LIKE cheap|inexpensive|affordable
tags LIKE "red-shoes"

Full-text searches are case-insensitive. Shoe and shoe produce the same results.

Unless you're using the exact word operator, the full-text search also matches similar words. For example, name LIKE nice also returns products whose name contains nicely or nicer.

Datafeedr API Client Library

Source Code | Documentation

Examples

To create a request signature, concatenate id, action and timestamp and generate a hex-encoded sha256 hash from the result, using your secret key as a key:

$aid = 'MYKEY';
$secret = 'MYSECRET';
$message = $aid . $action . $timestamp;
$signature = hash_hmac('sha256',
    $message,
    $secret,
    FALSE);

The API Client takes care of the signatures. Provide your id and secret when creating the API object:

$aid = 'MYKEY';
$secret = 'MYSECRET';
$api = new DatafeedrApi($aid, $secret);

Copyright © 2007 ~ 2016 Datafeedr | All rights reserved.