REST Service Integration

In case you can’t use the Java library directly (most likely because your system doesn’t run on the JVM), you can use the REST-service wrapper for smartquery. It’s delivered as a docker image and has to run in your environment.


Start the service

The service is provided as docker image on docker hub with the name commerceexperts/smartquery-service:1.0.13

The container has to be started with your API key set at the environment variable SQ_API_KEY. It exposes port 8081 that can be mapped to any port. Please consider, that the docker container needs access to the remote URLs mentioned above at the Requirements section.

# use the API key you'll receive from us
docker run -d --name=smartquery-service -e SQ_API_KEY=<YourS3cr3tAPIkey> -P commerceexperts/smartquery-service:1.0.13

Use the service

The service offers two endpoints to get a query mapping:

Service Endpoint V1

URL Scheme:
curl localhost:10240/smartquery/v1/test/working?userQuery=bierzellt -o -
# returns 'bierzelt' on success
# returns 'bierzellt' if no mapping was found or no data is available

The response is a simple string that either is the mapped query or in case no mapping was found, it’s the original user query. Redirects are not supported for that endpoint and won’t be returned, even if available.

Keep in mind, that SmartQuery starts fetching the mapping data, after the first request for a specific tenant was received. So the first ~5 seconds all mappings will return the input query as a response because no mapping data was fetched. A few seconds later you should get mapped queries (if data is available).

It’s possible to remove that startup latency by specifying the wanted tenants using the preloadTenants parameter described below. In that case the service will be ready as soon as the mappings are loaded.

Service Endpoint V2

URL Scheme:
curl localhost:10240/smartquery/v2/test/working?userQuery=bierzellt -o -
# returns:

The response is an object that contains the following properties:

  • userQuery: the entered user query
  • masterQuery: if the query could be mapped, the master query is set, otherwise it’s null.
  • searchQuery: the final search query. That’s the master or the user query.
  • redirect: URL to a landing page or null if no redirect was configured.
  • successful: true if the query could be handled by SmartQuery


Update Rate

Sets the rate (in seconds) at which the update should run. The value must be between 5 and 3600. This can be set as part of the JAVA_OPTS environment variable:


Preload Tenants

Specify tenants that should be loaded immediately after initialization. Can be set either via environment variable as a comma-separated list:


or as part of the JAVA_OPTS environment variable with one parameter per tenant:

JAVA_OPTS="-Dsmartquery.preloadTenants[0]=example.num1 -Dsmartquery.preloadTenants[1]=example.num2"

Basic Authentication

In case you want to enable basic auth, add the following properties to the JAVA_OPTS env variable.

JAVA_OPTS="-Dserver.auth.enabled=true -Dsecurity.user.password=<desired-password>"

The user that is linked to that password is user. To use a different username, add the property<your-username> to JAVA_OPTS.

If server auth is enabled but the password property is omitted, a random password will be generated and printed to stdout.


By default, several metrics are exposed in the prometheus format trough the /prometheus endpoint of the service. This endpoint exposes several basic metrics plus the metrics described in the monitoring section at the direct integration docs.

To disable this endpoint, add the following parameter to the JAVA_OPTS environment variable:


Trouble Shooting

  • If you forgot to specify the API key, the container won’t start.
  • In case you tried to access an unpermitted tenant/channel (maybe because you specified the wrong API key), you will see such a message in the logs of the service: update failed: FeignException: status 403 reading QueryApiTarget#getModificationTime(Tenant); content: {“message”:”Invalid authentication credentials”}
  • To get more information about the internal processes, enable debug loggging. Do that with the docker startup parameter -e JAVA_OPTS=””