Nyris API Documentation

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)

Search

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

The number of total search request during a specific timeframe
The number of products in your search index
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
        }
    }
}

WebApp (JS)

The fastest and easiest way to integrate visual search to your website is using our Javascript WebApp. All you have to do is to add some lines of code to the header or footer section of your website and you are ready to start testing.

What I need to start using this code?

All you need is your API key. Inside your HTML (best just before the closing </body> tag) add the following code:

<script>
window.nyrisSettings = {
    // Required
    apiKey: '<YOUR_API_KEY>',

    // Optional
    xOptions: 'default', // See "general request options" https://docs.nyris.io/#general-request-options
    jpegQuality: 0.9, // Quality of the scaled image sent to the api
    maxWidth: 500, // Maximal size of the scaled image
    maxHeight: 500,
    responseFormat: 'application/offers.complete+json', // See "response type" https://docs.nyris.io/#response-type
    instantRedirectPatterns: [ 'mysite.com' ] // If exactly one result is returned and it contains `mysite.com`,go directly to the link.
}
</script>
<script src="https://assets.nyris.io/libs/js/1.3/search/widget.js"></script>

Replace <YOUR_API_KEY> from the last step with your actual API key.

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

Sample

There is a sample page here where you can enter your API key and see the widget in action https://assets.nyris.io/libs/js/1.3/search/sample.html

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