Products API¶
Documentation for implementing an API read by Já product scraper.
Note
- This documentation refers to Já’s custom format for products. Many ecommerce platforms have support for Product Feeds in XML format, either built-in or through a plugin. For those platforms we recommend the following documentation:
API¶
Single endpoint that returns a list of products order by descending modification date. Pagination is optional, see Pagination and frequency of use.
Example response¶
{
"products": [
{
"id": "65DP600",
"title": "TCL 65\" 4K UHD LED Snjallsjónvarp 65DP600",
"price": 99995,
"sale_price": 95995,
"sale_price_start_date": "2018-11-01T00:00:00Z",
"sale_price_end_date": "2018-11-02T00:00:00Z",
"description": "TCL er sjónvarpsframleiðandi sem hét áður Thomson...",
"url": "https://example.com/tcl-65-led-uhd-smart",
"updated_at": "2018-11-01T09:28:13Z",
"brand": "TCL",
"availability": true,
"shipping_price": 500,
"images": [
"https://example.com/images/65DP600/main_image.jpg",
"https://example.com/images/65DP600/image2.jpg"
],
"ja_category": 74,
"category": [
"Raftæki",
"Hljóð og Mynd",
"Sjónvörp"
],
"group_id": null,
"group_options": null,
"specifications": [
{
"title": "Framleiðandi",
"value": "TCL"
},
{
"title": "Upplausn",
"value": "Ultra HD/4K (2160p)"
}
]
}
],
"meta": {
"total_items": 1000,
"api_version": 1
}
}
Pagination and frequency of use¶
If you have over 1000 products we recommend using pagination, for example return 250 products per page. We will use a page parameter to iterate over all products. Since products should be ordered by descending modification date we will just read the first pages as needed when we fetch partial data. We might fetch partial data a few times per day and we will fetch the whole product catalog once per day. If there is no pagination we fetch everything few times per day.
Example usage if API has pagination:
http://example.com/ja-products?page=1 # 06:00 - Few or no changes
http://example.com/ja-products?page=1 # 10:00 - Few or no changes
http://example.com/ja-products?page=1 # 14:00 - Multiple changes, need another page
http://example.com/ja-products?page=2 # 14:00 - Have received all changes
http://example.com/ja-products?page=1 # 18:00 - Few or no changes
http://example.com/ja-products?page=1 # 22:00 - Full fetch, will loop through every page
http://example.com/ja-products?page=2 # 22:00
http://example.com/ja-products?page=3 # 22:00
...
http://example.com/ja-products?page=13 # 22:01
http://example.com/ja-products?page=14 # 22:01 - Returns 404 or empty product set, will quit here
Já categories¶
To ensure your products are correctly categorized and to improve visibility you should include the ja_category field in your API. The value of the field should be the ID of the category. The list of categories is found here.
Product properties¶
id¶
Type: string
Example:
65DP600
Description: Products unique identifier. Use SKU where possible
title¶
Type: string
Example:
TCL 65" 4K UHD LED Snjallsjónvarp 65DP600
price¶
Type: integer
Example:
99995
Description: Price with tax included. If the product is on sale this will be the old price.
sale_price¶
Type: integer
Example:
95995
Description: Optional. Used when there is a sale on the product
sale_price_start_date¶
Type: string
Example:
2018-11-01T00:00:00Z
Description: Optional. Start date of sale price. Use the ISO 8601 standard.
sale_price_end_date¶
Type: string
Example:
2018-11-02T00:00:00Z
Description: Optional. End date of sale price. Use the ISO 8601 standard
description¶
Type: string
Example:
TCL er sjónvarpsframleiðandi sem hét áður Thomson...
Description: HTML formatting allowed.
url¶
Type: string
Example:
https://example.com/tcl-65-led-uhd-smart
updated_at¶
Type: string
Example:
2018-11-01T09:28:13Z
Description: Used to determine whether the product will be updated. Use the ISO 8601 standard
brand¶
Type: string
Example:
TLC
availability¶
Type: boolean
Example:
true
Description: Whether product is available in any store.
shipping_price¶
Type: integer, null
Example:
500
Description: Shipping price of product. Should be null if shipping is not available. 0 if shipping is free. -1 if shipping is available but the price is calculated later.
images¶
Type: array
Example:
["https://example.com/images/65DP600/main_image.jpg",
"https://example.com/images/65DP600/image2.jpg"]
Description: First image will be the main image used. Don’t submit a placeholder image.
category¶
Type: array
Example:
["Raftæki", "Hljóð og Mynd", "Sjónvörp"]
Description: The product category that you have defined for your product. Include the full category from least specific to most. The example shows a product undir Raftæki > Hljóð og mynd > Sjónvörp.
ja_category¶
Type: integer
Example:
74
Description: Optional. The ID of the Já category that best represents the product. See https://gagnatorg.ja.is/docs/products/v1/#ja-categories.
group_id¶
Type: string, null
Example:
65DP600
Description: Unique identifier for a group of product variants. Variants are a group of similar products and often differ in size and color. Each variant is it’s own product and can differ in price, description, availability etc. but have the same group_id.
group_options¶
Type: array, null
Example:
[{"title": "Litur", "value": "Rauður"},
{"title": "Stærð", "value": "64GB"}]
Description: Defines how the variants differ. Must be used when group_id is used.
specifications¶
Type: array
Example:
[{"title": "Framleiðandi", "value": "TCL"},
{"title": "Upplausn", "value": "Ultra HD/4K (2160p)"}]
Description: Optional. Specifications of the product.
JSON schema¶
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"$ref": "#/definitions/product"
}
}
},
"definitions": {
"product": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Products unique identifier. Use SKU where possible",
"examples": [
"65DP600"
]
},
"title": {
"type": "string",
"examples": [
"TCL 65\" 4K UHD LED Snjallsjónvarp 65DP600"
]
},
"price": {
"type": "integer",
"description": "Price with tax included. If the product is on sale this will be the old price.",
"examples": [
99995
]
},
"sale_price": {
"type": "integer",
"description": "Optional. Used when there is a sale on the product",
"examples": [
95995
]
},
"sale_price_start_date": {
"type": "string",
"format": "date-time",
"description": "Optional. Start date of sale price. Use the ISO 8601 standard.",
"examples": [
"2018-11-01T00:00:00Z"
]
},
"sale_price_end_date": {
"type": "string",
"format": "date-time",
"description": "Optional. End date of sale price. Use the ISO 8601 standard",
"examples": [
"2018-11-02T00:00:00Z"
]
},
"description": {
"type": "string",
"description": "HTML formatting allowed.",
"examples": [
"TCL er sjónvarpsframleiðandi sem hét áður Thomson..."
]
},
"url": {
"type": "string",
"examples": [
"https://example.com/tcl-65-led-uhd-smart"
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Used to determine whether the product will be updated. Use the ISO 8601 standard",
"examples": [
"2018-11-01T09:28:13Z"
]
},
"brand": {
"type": "string",
"examples": [
"TLC"
]
},
"availability": {
"type": "boolean",
"description": "Whether product is available in any store.",
"examples": [
true
]
},
"shipping_price": {
"type": ["integer", "null"],
"description": "Shipping price of product. Should be null if shipping is not available. 0 if shipping is free. -1 if shipping is available but the price is calculated later.",
"examples": [
500
]
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"description": "First image will be the main image used. Don't submit a placeholder image.",
"examples": [
"[\"https://example.com/images/65DP600/main_image.jpg\", \n\"https://example.com/images/65DP600/image2.jpg\"]"
]
},
"category": {
"type": "array",
"items": {
"type": "string"
},
"description": "The product category that you have defined for your product. Include the full category from least specific to most. The example shows a product undir Raftæki > Hljóð og mynd > Sjónvörp.",
"examples": [
"[\"Raftæki\", \"Hljóð og Mynd\", \"Sjónvörp\"]"
]
},
"ja_category": {
"type": [
"integer"
],
"description": "Optional. The ID of the Já category that best represents the product. See https://gagnatorg.ja.is/docs/products/v1/#ja-categories.",
"examples": [
74
]
},
"group_id": {
"type": [
"string",
"null"
],
"description": "Unique identifier for a group of product variants. Variants are a group of similar products and often differ in size and color. Each variant is it's own product and can differ in price, description, availability etc. but have the same group_id.",
"examples": [
"65DP600"
]
},
"group_options": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"required": [
"title",
"value"
],
"properties": {
"title": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Defines how the variants differ. Must be used when group_id is used.",
"examples": [
"[{\"title\": \"Litur\", \"value\": \"Rauður\"}, \n{\"title\": \"Stærð\", \"value\": \"64GB\"}]"
]
},
"specifications": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"value"
],
"properties": {
"title": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Optional. Specifications of the product.",
"examples": [
"[{\"title\": \"Framleiðandi\", \"value\": \"TCL\"}, \n{\"title\": \"Upplausn\", \"value\": \"Ultra HD/4K (2160p)\"}]"
]
}
},
"required": [
"id",
"title",
"price",
"url",
"updated_at",
"category"
]
},
"meta": {
"type": "object",
"properties": {
"total_items": {
"type": "integer",
"description": "Total count of products.",
"examples": [
1000
]
},
"api_version": {
"type": "integer",
"description": "Should be 1 for this version of the API."
}
}
}
}
}