Introduction
nyris API Documentation
Find API
SearchSearch CasesUsing OAuth 2: Getting an Access Token
Regions API
Object detection and region proposal
Analytics
AnalyticsClick and conversion analytics
Mobile SDK
Widget (JS)Android SDKiOS SDK
Product Data & Images
Submit your product data

nyris API Documentation

Welcome to nyris' API Documentation. nyris is a high performance visual product search, object detection and visual recommendations engine for retail and industry. This documentation covers our visual product search engine and the visual recommendations engine.

The implementation in your website or app comprises of three steps.

1. Submit your product & image data
In order to recognize your products, we need to know your products. The product feed section covers all details how to submit your product data to us and the specifications for your product or object images.

2. Implement nyris API in your app, website or messenger bot
The nyris engine can be integrated in your app, website, messenger bots, BI solutions - wherever you want to make your customers happy or optimize your data management process. We provide you with code examples on how to query our Find API and Regions API and have ready to go SDKs for iOS, Android and Xamarin.

3. Implement automated feedback in your app, website or messenger bot
By tying user interactions to automated feedback in our Feedback API, you allow for automatic statistic generation and continous improvement of the search results.

To get started, email us at support@nyris.io. Our team will provision API keys, or OAuth IDs and Secrets to access our API. Always feel free to contact us should you have questions or suggestions for our service or this documentation. In addition, you can always find our open source code github.com/nyris.

Thank You & happy coding!
Markus (CTO / Founder)

In order to find results, you send an image to our Find API. We will process the image and return a JSON object containing the metadata of the identified items. Use the provided API key for authentication; if applicable, you can also provide a session ID to correlate requests.

Search with filters

To search with filters, use the find/v1.1 endpoint (instead of find/v1). For searching with filters, image and filters should be sent as multipart/form-data. We will process the image with provided filters and return a JSON object containing the metadata of the identified items. The returned items will have the provided filter types and values.

Request Headers

Key Value
X-Api-Key The API key provided by us (preferred). OR
Authorization Bearer + 'access_token' when OAuth is used.
Content-Type Either image/jpeg or image/png .
Content-Length The size of image in bytes.
X-Session (Optional) A valid session identifier to correlate multiple requests.

If no value is provided for the X-Session header (or session query argument) a new session is started and its ID will be returned with the response (see Response Headers below). Front-ends are encouraged to pass the session ID returned by the previous request to the next request, thereby linking requests together. To start a new session later on, simply do not send the X-Session header (nor the session query argument) or provide an empty value for it.

Request body

The body of the request should contain the image file's actual bytes sent in binary.

Request body with filters

For searching with filters, image and filters should be sent as multipart/form-data. Multiple filters types and values can be sent. The AND operator will be used in the search between all filter types and the OR operator - between all filter values of given filter type.

Filter schema

Name Type Explanation
filterType String The filter type, exmaple: color
filterValues String [] The filter values, example: [red, blue]

General Note on Image Submission

  • Any image manipulation (resizing, compressing, cropping) should be done directly on user’s device, be it a mobile device or a desktop computer.

  • The preferred image dimension sent to regions API or find API is 1 Mpx, regardless of image’s aspect ratio. This means the image may have a dimension of 1000 x 1000 px, 2000 x 500 px or any combination of values with a product of 1,000,000 px. Any aspect ratio is tolerated, but extreme values should be avoided for quality reasons.

  • Larger images will be accepted as well but generally do not improve search accuracy and should therefore be resized before being sent to our APIs. Images exceeding a file size of approximately 2 MB will be rejected with a 413 status code. A good image size is around 100 kB; on average, our received request images are at about 50 KB in JPEG/JFIF format.

  • The minimum size of the image should be 100 px on the shortest edge. Images that are too small do not provide enough details and will be rejected with a 460 status code.

  • The image format must be JPEG/JFIF or PNG; JPEG/JFIF requests should be preferred for size reasons. Requests containing other image formats (e.g. WebP) are rejected.

  • All cropping and cutting steps should be applied to the original image and only then resized and sent to the nyris APIs.

  • Please contact us at support@nyris.io if you have any questions regarding image handling.

Response Headers

Requests are automatically tagged with a Request ID and a Session ID. These are returned in following headers:

Key Value
X-Matching-Request The identifier of the request; used for tracing and with the Feedback API .
X-Session A session identifier covering multiple requests; used for tracing and with the Feedback API.

Regular request

POST
https://api.nyris.io/find/v1

Request with filters (by multipart/form-data)

POST
https://api.nyris.io/find/v1.1

Session-correlated request (by URL argument)

POST
https://api.nyris.io/find/v1?session=xxxxxx

Example Request

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.nyris.io/find/v1")
  .post(null)
  .addHeader("x-api-key", "KEY")
  // or instead of the api-key .addHeader("authorization", "Bearer access-token")
  .addHeader("x-session", "..."), // optional
  .addHeader("content-type", "image/jpeg")
  .addHeader("content-length", "image-file-size-in-bytes")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example with filters

OkHttpClient client = new OkHttpClient();
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
            .addFormDataPart("filters[0].filterType","color")
            .addFormDataPart("filters[0].filterValues[0]","Red")
            .addFormDataPart("image","image.jpg",
RequestBody.create(MediaType.parse("application/octet-stream"),
            new File("image.jpg")))
            .build();
            
Request request = new Request.Builder()
              .url("https://api.nyris.io/find/v1.1")
              .method("POST", body)
              .addHeader("x-api-key", "<SET_YOUR_KEY_HERE>")
              .addHeader("cache-control", "no-cache")
              .build();

Response response = client.newCall(request).execute();

Example minimal response

{
    "id": "c7ac45c0165a54feb005aa2049f19235",
    "session": "c7ac45c0165a54feb005aa2049f19235",
    "results": [
        {
            "sku": "123454643",
            "score": 0.96
        },
        {
            "sku": "123454644",
            "score": 0.92
        },
        {
            "sku": "123454645",
            "score": 0.88
        },
        {
            "sku": "123454646",
            "score": 0.83
        }
    ]
}

Authentication

Two authentication methods are supported. The first one is by simply sending the key provided by nyris in a X-Api-Key header. The second one is by obtaining an authorization token from our OAuth server (https://api.nyris.io/connect/token), then send it in the Authorization header.

When to authenticate via the X-Api-Key header?

The X-Api-Key is the common authentication method. If you want all your users to use the search. Then it's easier to directly use the API key.

When to authenticate via an OAuth token?

Unlike the API key, authentication tokens have an expiry time. Which make them more suitable for scenarios where only certain users only have access to the search. By generating a token for each user, you are sure that the token will expire if it get compromised.

A common scenario is a web-based application on the public internet in which the server back-end securely obtains an access token that is then handed out to the front-end. Even if that token gets compromised, it is only valid for a limited duration.

What if I don't want to share the API key or a token with users?

If you want to control each request then the only solution is to create your own proxy that forwards the requests to the server. That way you can have your own authentication method and a control over each request.

How do I obtain an OAuth token?

You can obtain an access token by following a Client Credentials flow against the https://api.nyris.io/connect/token endpoint. To obtain the necessary Client ID and Client Secret credentials, please reach out to our support.

This process is explained in the section Get an Access Token.

Additional Header Attributes

There are additional header attributes you can use to change the results. Please find the overview below

Language Header

In case you are providing us two different feeds for the same products using different languages, you can use the Accept-Language header to filter the results by a specific language.

Header Example Value
Accept-Language de-CH
Accept-Language fr-CH

If you don't set the Accept-Language header, the results for all languages will be returned.

Response type

Format guarantees

We will ensure that existing fields will not be removed or have their type changed.

Additional fields can be added at any point in time. Because of that, application code needs to gracefully ignore unknown fields of the JSON reponse.

Content negotiation

By default, a minimal response format is produced. You can vary the response using the Accept header:

Header Value Description
Accept application/minimal+json Return minimal response (the default)
Accept application/items.complete+json Return all available fields

Note that you need to provide us the appropriate data in your product data feed in order for us to display them. Fields which have no value will not be included in the JSON response.

Example response with all available fields

{
	"id": "c7ac45c0165a54feb005aa2049f19235",
	"session": "c7ac45c0165a54feb005aa2049f19235",
	"results": [{
		"title": "test product",
		"descriptionShort": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
		"descriptionLong": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat.",
		"language": "de-DE",
		"brand": "test brand",
		"catalogNumbers": ["test_catalog_number_0",
		"test_catalog_number_1"],
		"customIds": {
			"DEMO_CUSTOM_ID": "DEMO_ID_123"
		},
		"keywords": ["demo", "demonstration", "test"],
		"categories": ["Demo", "Test"],
		"availability": "in stock",
		"feedId": "1",
		"groupId": "1",
		"price": "10.00 EUR",
		"salePrice": "1.00 EUR",
		"links": {
			"main": "https://www.mingaberlin.com/de/bunte-socken-muster-sliced-sunburst.html",
			"mobile": "https://www.mingaberlin.com/media/catalog/product/cache/2/thumbnail/100x100/0dc2d03fe217f8c83829496872af24a0/0/0/0086.jpg"
		},
		"images": ["https://img.staging.everybag.net/809/809450e02adc0a9bd52a19f6a212307ad9803323b5c42ab9b4d29eb27fa73b7f.jpg",
		"https://img.staging.everybag.net/2b4/2b4f7ac06c51e55b8de382667a45bfa37082c87f019be7848d8abbbc4869acb5.jpg"],
		"metadata": "This product is for demonstrations only",
		"sku": "123456",
		"score": 1,
		"filters": {
			"foo": [
				"Beauty"
			],
			"product": [
				"unknown"
			]
		}
	}]
}

General Request Options

You can control basic search parameters such result count and thresholds by using the X-Options header. Parameters are specified as key=value pairs be separated by a space character, e.g. X-Options: limit=10 threshold=0.5.

Parameter Example Value Explanation
limit limit=20 (default) , integers between 1 and 100 The upper limit for the number of results to be returned.
threshold threshold=0.8 The final threshold to apply to the scores. Only results above or equal to that score will be returned.

Geolocation Parameters

If products in the feed are provided with geolocation, the information can be used to narrow down specifying a maximal distance between the user and the product. The provided coordinates have to be in the WGS84 format with signed decimal numbers as the notation. The following query parameters are required:

Name Example Explanation
lat 52.5200 The latitude of the user.
lon 13.4050 The longitude of the user.
dist 10000 The distance from the center in meter.

If find/v1.1 endpoint is used, the geolocation parameters should passed by multipart/form-data.

POST
https://api.nyris.io/find/v1?lat=LAT&lon=LON&dist=DIST

Example with filters

Search Cases

Visually Similar Products by SKU

To get visually similar items for a specific product in your catalogue, you can also submit just the SKU of this product to us. As we already know this product (because we imported it for you) we perform the visual similarity search based on the main image of this product.

To use the visual recommendation engine with your SKU please send a simple GET request with your SKU to the following endpoint:

API Endpoint (GET) https://api.nyris.io/recommend/v1/

Example for SKU 03764560: https://api.nyris.io/recommend/v1/03764560

The response will not include the product with the SKU you have send with the request. Although this would be the most similar product, it's the same product as the product you have send the request for, so it's removed from the results set.

GET
https://api.nyris.io/recommend/v1/

Example minimal response

{
    "results": [
        {
            "sku": "123454643",
            "score": 0.96
        },
        {
            "sku": "123454644",
            "score": 0.92
        },
        {
            "sku": "123454645",
            "score": 0.88
        },
        {
            "sku": "123454646",
            "score": 0.83
        }
    ]
}

Using OAuth 2: Getting an Access Token

For implementation simplicity consider using the API key based authentication instead.

Once you have the Client ID and Client Secret, you have to generate an access token to use our API end points. Generating a token requires a POST request to the OAuth / OpenID Server with an URL encoded form.

Property Description
grant_type client_credentials
client_id required
client_secret required
scope image_matching
POST
https://api.nyris.io/connect/token

Example request

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=image_matching");
Request request = new Request.Builder()
  .url("https://api.nyris.io/connect/token")
  .post(body)
  .addHeader("content-type", "application/x-www-form-urlencoded")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example response

{
    "token_type": "Bearer",
    "access_token": "your-unique-access-token",
    "expires_in": 2592000
}

Object detection and region proposal

The Find API always matches on the entire image. While this is a sane default, you may want to crop the image to specific areas first in order to improve matching performance. The Regions API assists you by identifying parts of the image that are likely to contain relevant objects, allowing front-ends to quickly propose your end-users sections of the image to search with.

To obtain region proposals for an image, use the find/v2/regions endpoint (instead of find/v1 used for matching).
Note: The find/v1/regions endpoint is deprecated and should not be used anymore.

Request Headers

Key Value
X-Api-Key The API key provided by us (preferred). OR
Authorization Bearer + 'access_token' when OAuth is used.
Content-Type Either image/jpeg or image/png .
Content-Length The size of image in bytes.

Response format

The API will respond with a JSON document containing a single propert regions:

Property comment 
regions An array of region documents.

Each region document is defined as:

Property comment 
confidence A confidence value (range 0..1 ) that describes the confidence in an object being detected at that location.
region The coordinates of an axis-aligned bounding box.

The region box has the following properties:

region value comment 
top The top-most coordinate in pixels (floating point).
left The left-most coordinate in pixels (floating point).
bottom The bottom-most coordinate in pixels (floating point).
right The right-most coordinate in pixels (floating point).

Note that the pixel coordinates reported are in the coordinate frame of the image sent to the server, e.g. a region covering a 100 × 200 pixel image would report values of "bottom": 200.0, "right": 100.0.

HTTP Request

POST
https://api.nyris.io/find/v2/regions

Example Request

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.nyris.io/find/v2/regions")
  .post(null)
  .addHeader("x-api-key", "KEY")
  // or instead of the api-key .addHeader("authorization", "Bearer access-token")
  .addHeader("x-session", "..."), // optional
  .addHeader("content-type", "image/jpeg")
  .addHeader("content-length", "image-file-size-in-bytes")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example response

{
    "regions": [
        {
            "confidence": 0.8876233,
            "region": {
                "top": 43.0,
                "left": 153.0,
                "bottom": 577.0,
                "right": 427.0
            }
        }
    ]
}

Analytics

Visual search analytics provide valuable insight into your customers search behavior and at the same time give us valuable input to improve the visual search performance.

There are two kind of analytics that we offer

  • General usage and search index analytics (no implementation on merchant site required)
  • Click and conversion analytics (implementation on merchant site required to track customer events)

Our general search analytics will provide you with

  1. The number of total search request during a specific timeframe
  2. The number of products in your search index
  3. The number of images in your search index

Our click and conversion analytics are described in the following sections.

Click and conversion analytics

In order to improve our visual search, we need to know what happens after we delivered the visual search results. Each request we deliver to you has a unique Request ID found in the X-Matching-Request response header, alongside a session ID in the X-Session response header.

Using the Request ID and our Feedback API, you can submit multiple events to our analytics engine. Below you will find the list of events and the API endpoint including an example how to use it.

Sending customer events to nyris analytics engine

In order to implement click and conversion analytics on your site, you need to send nyris all click and conversion events to the feedback endpoint using an HTTP POST to https://api.nyris.io/feedback/v1:

Please use the provided API-Key in the header for authentication. The Feedback API accepts only valid JSON documents. As a result we require the following request headers to be set:

Request Header Value 
X-Api-Key The API Key provided by us.
Content-Type Either application/event+json , application/json or text/json .

The submitted JSON document has to include the following fields:

Property comment 
request_id The Request ID
session_id optional, the first Request ID for the same user. The session_id can group multiple requests from a single user
timestamp The timestamp of the event
event The event type (see below)
data The data specific to the event type (see below; optional for some)

The possible event types are:

event value comment 
click Indicates which position in the result list and/or which specific Product ID was clicked or selected by an end-user.
conversion Indicates a customer-specific conversion event.
feedback Indicates end-user feedback on the entire set of returned search results.
region Indicates a region of the original image was submitted to the Find API (e.g. when using object proposal).

The individual event types and their data payloads are detailed in the following sections alongside some reference examples.

HTTP Request

POST
https://api.nyris.io/feedback/v1

Example JSON Body

{
    "request_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "session_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "timestamp": "2020-11-06T17:53:25.511Z",

    "event": "feedback",
    "data": {
        "success": true
    }
}

Click events

This event tracks the position and the ID of the clicked item in the results set. Its data field is required and has the following properties:

data Property comment 
product_ids An array of string values, containing the Product IDs.
positions An array of int16 values describing the zero-based index of the result returned by our Find API.

Providing the Product IDs instead of (just) the indexes is helpful especially in the presence of possible re-ordering or filtering in a front-end. Note that each individual Product ID has to be the same as in your product data, as otherwise we will be unable to correlate the information.

JSON Example

{
    "request_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "session_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "timestamp": "2020-11-06T17:53:25.511Z",

    "event": "click",
    "data": {
        "positions": [10],
        "product_ids": ["1234"]
    }
}

Conversion events

This event tracks any merchant defined conversion value (e.g. add to cart, sale, view). It behaves similar to the click event but conveys the notion that a result wasn't just interacted with once, it also provided value. Its data field is optional and has the following properties:

data Property comment 
product_ids An array of string values, containing the Product IDs.
positions An array of int16 values describing the zero-based index of the result returned by our Find API.

Unlike in a click event, sending the conversion event without any data will work as well. This works because a click event should precede an conversion; in any case, this will mark a request as successful.

JSON Example

{
    "request_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "session_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "timestamp": "2020-11-06T17:53:25.511Z",

    "event": "conversion",
    "data": {
        "positions": [10],
        "product_ids": ["1234"]
    }
}

User feedback events

This event tracks end-user feedback on search results. Its data field is required and has the following properties:

data Property comment 
success A boolean resembling general business success of a result.
comment An optional string containing verbatim user feedback.

This event is meant to be issued as a result of a direct end-user feedback e.g. as collected from a "Did we find what you were looking for" form / button set.

This event's success value will label the whole request as either successful or to be improved. If possible, click and conversion events should be provided in addition as they provide automatic feedback.

JSON Example

{
    "request_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "session_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "timestamp": "2020-11-06T17:53:25.511Z",

    "event": "feedback",
    "data": {
        "success": true,
        "comment": "Thank you!"
    }
}

Image region events

This event tracks the customer selected image region in the presence of any cropping or region selection mode. Its data field is required and has the following properties:

data Property comment 
rect The normalized region rectangle that is sent to the Find API.

The data.rect property is a structure describing the normalized coordinates of the selected region:

rect Property comment 
x The left coordinate of the region as a fraction of the image width (range 0..1 ).
y The top coordinate of the region as a fraction of the image height (range 0..1 ).
w The width of the region as a fraction of the image width (range 0..1 ).
h The height of the region as a fraction of the image height (range 0..1 ).

Normalized coordinates and sizes are simply pixel values divided by the highest allowed pixel value along the dimension, thereby making the selection independent of the actual transmitted size of the image. As an example, a region covering the entire image would start at "x": 0.0, "y": 0.0 and have the size "w": 1.0, "h": 1.0.

JSON Example

{
    "request_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "session_id": "e8848827-27af-41d7-a98f-1a2f94b0f19a",
    "timestamp": "2020-11-06T17:53:25.511Z",

    "event": "region",
    "data": {
        "rect": {
            "x": 0.25,
            "y": 0.25,
            "w": 0.5,
            "h": 0.5
        }
    }
}

Widget (JS)

The fastest and easiest way to integrate visual search to your website is using our Javascript Widget. All you have to do is to add some lines of code to a runtime file of your website and you are ready to start using visual search.

What I need to start using this code?

You need to follow these steps:

  1. Copy the script into a text editor and configure the settings parameters.

  1. After making the necessary updates, copy all the lines and add to the runtime file (ex. index.html) to embed the visual search widget into your platform.

Done. You are ready to use visual search on your website!

Sample

See the nyris demo widget in action: https://widget.nyris.app/

Where is the source code? Can I change it

The code is on github. Follow the readme file to build the project. You can change or adjust the JS / CSS files according to your needs and host them on your server as well.

Android SDK

You can find the latest Android SDK including the implementation documentation on github:

https://github.com/nyris/SDK.Android

iOS SDK

You can find the latest iOS SDK including the implementation documentation on github:

https://github.com/nyris/Nyris.IMX.iOS

Should you have any questions, please send and e-mail to support@nyris.io

Submit your product data

There are several ways to submit your product and image data to us. We can import nearly every structured data format (xml, csv, txt, json, etc.). If you are already providing your data to an affiliate network like Affilinet, Awin or Google Shopping, you are probably all set for the start. In this case we just need access to your feed URL. Please be aware that those feeds usually only include the link to the main product image. As image recognition works best the more images of a specific product we have, you might need to adjust those feeds to include all your product images. Please find more details below.

Feed Format & Updates

  • The feed can be submitted as csv, xml, txt or json file
  • Preferred encoding for the files is UTF-8
  • For csv, please use if possible "," as delimiter and " " for enclosing text
  • Please provide us with a link to your feed. If the access to the feed is secured with username/password, please also provide us those credentials
  • Please revise your server seetings in order to ensure that the IP address we use to access your server remains unblocked at all times in spite of frequent accessing
  • You feed will be imported daily. Should you need shorter import cycles, please contact support@nyris.io

If you don't have a product feed, we can also directly access your product data trough an API for the following systems:

Shop Systems.

  • BigCommerce
  • Magento 1.x SOAP
  • PrestaShop
  • Shopify
  • WooCommerce

PIM

  • Akeneo
  • hybris

You can also create a data feed using Google Sheets. Details on how to use Goole Sheets and an example file can be found in a section below.

Available Feed Attributes

The bare minimum is a unique ID (sku) and the main_image_link. To get a full list of possible attributes please download the following sheet or use a copy of it as base for your item or product feed. When gathering your data, please keep always in mind that all submitted information will be used for improving your search results. Completeness and quality of data often makes the difference:

Download Feed Example and full attribute description (google sheets)

Required Fields

Attribute Example Comment
sku sku1 unique item or product identifier (e.g. EAN code)
main_image_link http://cdn.nyris.io/image.jpg main image link. should be publicly available. ideally, product in question should be at the center of the image

Optional Fields

Image Links

To improve the search, additional images can be provided. All referenced images (main, additional and recognition types) are used for search. main and additional images are treated identically, with the main image being the designated reference to be shown e.g. in the Portal. If requested, these image links can be returned as part of the response. recognition image links, on the other hand, are purely used for recognition and are never returned as part of any response.

Attribute Example Comment
additional_image_link_0 http://cdn.nyris.io/image_a1.jpg additional images
additional_image_link_1 http://cdn.nyris.io/image_a2.jpg additional images
additional_image_link_N http://cdn.nyris.io/image_aN.jpg Nth additional image
recognition_image_link_0 http://cdn.nyris.io/image_r1.jpg additional recognition images (images that will never show up on frontend) ideally taken from different angles and w/o packaging
recognition_image_link_1 http://cdn.nyris.io/image_r2.jpg additional recognition images (images that will never show up on frontend** ideally taken from different angles and w/o packaging
recognition_image_link_N http://cdn.nyris.io/image_rN.jpg Nth additional recognition image

Textual description

Providing these values will enable both OCR (text matching) functionality, finer grained recognition of results and item class distribution results. While optional, providing these values is thus strongly recommended.

Attribute Example Comment
title title 1 Product or item title (supports OCR recognition step)
brand brand 1 Brand (supports brand recogntion step)
description_short description short 1 Short description (supports OCR recognition step)
description_long description long 1 Long description (supports OCR recognition step)
custom_category cat1 > cat2 your product or item category. Please separate with > (e.g. building materials, wood, windows & doors > windows > window ledges). Providing this field will be used to improve recommendations.
language de-DE Language Culture Name ( https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/db9b9b72-b10b-4e7e-844c-09f88c972219 )

Key-value pairs

By providing custom key-value pairs, we are able to improve detection in combination with text matching functionality, and/or will be able to return named IDs as part of the response. If your system requires multiple IDs or custom data pairs, use these fields.

Attribute Example Comment
custom_id_key_0 pzn custom ID key (e.g. for Barcode recognition) and
custom_id_value_0 123456 custom ID value (e.g. for Barcode recognition),
custom_id_key_N pzn Nth custom ID key and
custom_id_value_N 123456 Nth custom ID value

Catalog numbers

These values are mainly used for identifying products within catalogs, and catalogs by IDs.

Attribute Example Comment
catalog_number_0 3306 catalog numbers from your printed advertisment. Used by PDF importer
catalog_number_1 cat1 catalog numbers from your printed advertisment. Used by PDF importer
catalog_number_N ... Nth catalog number

Keywords

These values are used for exactly matching keywords, such as item materials, colors, etc., with text found during OCR; thus, providing these values improves text matching. Keywords are treated as a set, so values specified multiple times would be considered identical.

To simplify specification of keywords, you can specify keywords in a delimiter-separated list via the configurable keywords column. By default, keywords are split at the , (comma) delimiter:

Attribute Example Comment
keywords keyword, keyword, keyword 2 Registers the two keywords keyword and keyword 2
keyword(",") keyword 1, keyword 2 Registers the two keywords keyword 1 and keyword 2
keyword("AND") keyword 1 AND keyword 2 Registers the two keywords keyword 1 and keyword 2

To provide single keywords or individual keywords per column, use the keyword / keyword_N variant instead. Here, values are not split:

Attribute Example Comment
keyword a nice, individual keyword Registers the keyword a nice, individual keyword
keyword_0 keyword 0 The first keyword in a set
keyword_1 keyword 1 The second keyword in a set
keyword_N ... The Nth keyword in a set

Geolocation Fields

If provided, the coordinates can be used to narrow down the search by the location of the product. The provided coordinates have to be in the WGS84 format with signed decimal numbers as the notation.

Attribute Example Comment
latitude 52.5200 Latitude of the product. Use together with longitude to associate the product with a location.
longitude 13.4050 Longitude of the product. Use together with latitude to associate the product with a location.

Item relations

Some items are related to other entries, and some IDs may have different meaning across logical separations of feeds (e.g. when there is a feed per country).

Attribute Example Comment
feed_id 1 Feed ID, required only if you have multiple feeds as one merchant. The value has to be an integer.
group_id 23 for variation products (size, colour etc. variations)

Item URLs

Attribute Example Comment
main_offer_link http://www.nyris.io/1 product or landing page link
mobile_offer_link http://m.nyris.io/landing secondary product or landing page link (mobile, video etc.)

PreFilter Attributes

Attribute Example Comment
filter_key_0 color filter key used by faceted search and
filter_value_0 Red,Blue comma separated filter values for the key for the item,
filter_key_N shape Nth filter key (Max N = 10) and
filter_value_N candle,capsule Nth filter values for the item

Other Optional Fields

Attribute Example Comment
meta_data some additional text data any data you would like to store additionally (text field); the content is not interpreted
availability in stock valid values: in stock , out of stock , preorder , back in stock soon , removed
price 17.30 EUR . as decimal, 3-digit ISO Code for currency
sale_price 15.00 EUR . as decimal, 3-digit ISO Code for currency
Show examples in:
JavaPythonJScspphpswift
nyris API Documentation