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:0.11.0

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:0.11.0

Use the service

The service offers a single endpoint with a single method. To get a mapping, please send the following request with the placeholders resolved.

Service Endpoint

For Example:

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 contains a mapped query or in case no mapping was found, it’ll contain the input query.

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 response, because no mapping data was fetched. A few seconds later you should get changed queries (if data is available).

It’s possible to lower that startup latency by specifying the tenants using the preloadTenants parameter, that is described below.


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"


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 specifiy 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 log. Do that with the docker startup parameter -e JAVA_OPTS=””