{"id":26103318,"url":"https://github.com/constructor-io/constructorio-java","last_synced_at":"2025-04-12T17:23:42.671Z","repository":{"id":4964963,"uuid":"44415416","full_name":"Constructor-io/constructorio-java","owner":"Constructor-io","description":" A Java REST client for the Constructor.io API","archived":false,"fork":false,"pushed_at":"2025-04-11T07:23:29.000Z","size":4483,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-12T17:23:10.883Z","etag":null,"topics":["autocomplete","constructorio","constructorio-integrations","http","java","rest-client","search"],"latest_commit_sha":null,"homepage":"https://constructor.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Constructor-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-16T23:12:25.000Z","updated_at":"2025-03-31T17:43:38.000Z","dependencies_parsed_at":"2024-08-27T00:04:00.736Z","dependency_job_id":"6e72db93-77c4-4507-9930-d806ebd3ff8a","html_url":"https://github.com/Constructor-io/constructorio-java","commit_stats":null,"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Constructor-io","download_url":"https://codeload.github.com/Constructor-io/constructorio-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248602865,"owners_count":21131703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","constructorio","constructorio-integrations","http","java","rest-client","search"],"created_at":"2025-03-09T20:06:21.877Z","updated_at":"2025-04-12T17:23:42.624Z","avatar_url":"https://github.com/Constructor-io.png","language":"Java","readme":"[![Release](https://jitpack.io/v/Constructor-io/constructorio-java.svg)](https://jitpack.io/#Constructor-io/constructorio-java) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Constructor-io/constructorio-java/blob/master/LICENSE)\n\n# Constructor-IO Java Client\n\n[Constructor.io](http://constructor.io/) provides search as a service that optimizes results using artificial intelligence (including natural language processing, re-ranking to optimize for conversions, and user personalization).\n\n# Documentation\n\nFull API documentation is available on [Github Pages](https://constructor-io.github.io/constructorio-java/)\n\n# Requirements\n\nRequesting results from your JVM based back-end can be useful in order to control result rendering logic on your server, or augment/hydrate results with data from another system. However, a back-end integration has additional requirements compared to a front-end integration. Please review the [Additional Information For Backend Integrations](https://github.com/Constructor-io/constructorio-java/wiki/Additional-Information-for-Backend-Integrations) article within the wiki for more detail.\n\n# Installation\n\n1. Follow the directions at [Jitpack.io](https://jitpack.io/#Constructor-io/constructorio-java/v6.3.2) to add the client to your project.\n2. Retrieve your autocomplete token and key.  You can find this at your [Constructor.io dashboard](https://constructor.io/dashboard).\n3. Create a new instance of the client.\n\n```java\nConstructorIO constructor = new ConstructorIO(\"apitoken\", \"apikey\", true, null);\n```\n\n# Creating and Modifying Items\n\nA `ConstructorItem` contains all the information about a product or search suggestion. To add or replace a batch of items, you will need to provide an array of `ConstructorItem`'s and their relevant `Autocomplete Section`.\n\n```java\n// Create an array of items\nConstructorItem[] items = new ConstructorItem[20];\nitems[0] = new ConstructorItem(\"10001\");\nitems[1] = new ConstructorItem(\"10002\");\n...\nitems[19] = new ConstructorItem(\"10003\");\n\n// Add or replace items in the Products section\nconstructor.createOrReplaceItems(items, \"Products\"); // (limit of 1,000 items)\n```\n\nTo update existing item(s), you will need to provide an array of `ConstructorItem`(s) and their relevant `Autocomplete Section`.\nYou can pass in an \"onMissing\" enum to tell the system how to handle updating items that don't exist (possible values are \"FAIL\" | \"IGNORE\" | \"CREATE\").\n\n```java\nConstructorItem item = new ConstructorItem(\"10001\");\nitem.setSuggestedScore((float) 1337.00);\nConstructorItem[] items = { item };\n\n// Update item(s) from the Products section\nconstructor.updateItems(items, \"Products\", false, null, CatalogRequest.OnMissing.IGNORE);\n```\n\n# Deleting Items\n\nTo delete existing item(s), you will need to provide an array of `ConstructorItem`(s) and their relevant `Autocomplete Section`.\n\n```java\n// Create an item\nConstructorItem item = new ConstructorItem(\"10001\");\nConstructorItem[] items = { item };\n\n// Delete items from the Products section\nconstructor.deleteItems(items, \"Products\"); // (limit of 1,000 items)\n```\n\n# Retrieving Items\n\nRetrieving your items.\n\n```java\nItemsRequest request = new ItemsRequest();\nItemsResponse response = constructor.retrieveItems(request);\n```\n\nYou can also specify certain ids to retrieve.\n\n```java\nItemsRequest request = new ItemsRequest();\nrequest.setIds(Arrays.asList(\"10001\", \"10002\"));\nItemsResponse response = constructor.retrieveItems(request);\n```\n\nRetrieving your items as a JSON string.\n\n```java\nItemsRequest request = new ItemsRequest();\nString response = constructor.retrieveItemsAsJson(request);\nJSONObject jsonObj = new JSONObject(response);\nJSONArray itemsArray = jsonObj.getJSONArray(\"items\");\n```\n\n# Replacing and Updating Catalogs\nTo replace or update your product catalog, you will need to create a `CatalogRequest`. In this request, you can specify the files you want to upload (items, variations, and item groups) and the section you want to upload to. You can also set a notification e-mail to be alerted when a file ingestion fails.\n\n```java\n// Create a files map and add the relevant files\nMap\u003cString, File\u003e files = new HashMap\u003cString, File\u003e();\nfiles.put(\"items\", new File(\"src/test/resources/csv/items.csv\"));\nfiles.put(\"variations\", new File(\"src/test/resources/csv/variations.csv\"));\nfiles.put(\"item_groups\", new File(\"src/test/resources/csv/item_groups.csv\"));\n\n// Create a CatalogRequest with files to upload and the section to upload to\nCatalogRequest request = new CatalogRequest(files, \"Products\");\n\n// Set a notification e-mail\nrequest.setNotificationEmail(\"integration@company.com\");\n\n// Set the force flag if the catalog should be processed even if it will invalidate a large number of existing items\nrequest.setForce(true)\n\n// Send a request to replace the catalog (sync)\nconstructor.replaceCatalog(request);\n\n// Or send a request to update the catalog (delta)\nconstructor.updateCatalog(request);\n```\n\n\n# Retrieving Autocomplete Results\n\nTo retrieve autocomplete results, you will need to create an `AutocompleteRequest`. In this request you can specify the number of results you want per autocomplete section.  If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.\n\n```java\n// Create an AutocompleteRequest with the term to request results for\nAutocompleteRequest request = new AutocompleteRequest(\"rain coat\");\n\n// Define the number of results to show per section\nMap\u003cString, Integer\u003e resultsPerSection = new HashMap\u003cString, Integer\u003e();\nresultsPerSection.put(\"Products\", Integer.valueOf(6));\nresultsPerSection.put(\"Search Suggestions\", Integer.valueOf(8));\nrequest.setResultsPerSection(resultsPerSection);\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Add a variations map to request specific variation attributes as an array or object (optional)\nVariationsMap variationsMap = new VariationsMap();\nvariationsMap.setdType(VariationsMap.Dtypes.array);\nvariationsMap.addGroupByRule(\"variation\", \"data.variation_id\");\nvariationsMap.addValueRule(\"size\", VariationsMap.AggregationTypes.first, \"data.facets.size\");\nrequest.setVariationsMap(variationsMap);\n\n// Request results as an object\nAutocompleteResponse response = constructor.autocomplete(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.autocompleteAsJSON(request, userInfo);\n```\n\n# Retrieving Search Results\n\nTo retrieve search results, you will need to create a `SearchRequest`. In this request you can specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.\n\n```java\n// Create a SearchRequest with the term to request results for\nSearchRequest request = new SearchRequest(\"peanut butter\");\n\n// Add in additional parameters\nrequest.setResultsPerPage(5);\nrequest.setPage(1);\nrequest.setGroupId(\"625\");r\nrequest.setSortBy(\"Price\");\nrequest.setSortAscending(true);\nrequest.getFacets().put(\"Brand\", Arrays.asList(\"Jif\"))\n\n// Add the following paramaters to request for hidden fields or facets\nrequest.getHiddenFields().add(\"hidden_price_field\");\nrequest.getHiddenFacets().add(\"hidden_brand_facet\");\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Add a variations map to request specific variation attributes as an array or object (optional)\nVariationsMap variationsMap = new VariationsMap();\nvariationsMap.setdType(VariationsMap.Dtypes.array);\nvariationsMap.addGroupByRule(\"variation\", \"data.variation_id\");\nvariationsMap.addValueRule(\"size\", VariationsMap.AggregationTypes.first, \"data.facets.size\");\nrequest.setVariationsMap(variationsMap);\n\n// Request results as an object\nSearchResponse response = constructor.search(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.searchAsJSON(request, userInfo);\n```\n\nIf you'd like to retrieve search results asynchronously, the above code can be modified slightly to utilize a callback methodology:\n\n```java\nconstructor.search(request, userInfo, new SearchCallback() {\n  @Override\n  public void onFailure(final ConstructorException exception) {\n    // failure condition\n  }\n\n  @Override\n  public void onResponse(final SearchResponse response) {\n    // success condition - data located within `response`\n  };\n});\n```\n\n## Retrieving a breakdown of number of search results per algorithm\n\nTo determine number of results coming from token matching algorithm vs. cognitive embeddings algorithm, you can use the `ResultSources` object under the response.\n\n```java\n// Request results as an object\nSearchResponse response = constructor.search(request, userInfo);\nInteger resultsFromTokenMatching = response.getResponse().getResultSources().getTokenMatch().getCount();\nInteger resultsFromCognitiveEmbeddings = response.getResponse().getResultSources().getEmbeddingsMatch().getCount();\n```\n\n# Retrieving Search Results for Speech\n\nTo retrieve search results for text that originated from speech transcription rather than typing, you will need to create a `NaturalLanguageSearchRequest`. In this request you can specify the number of results you want per page and the page you want.  All other information is inferred from the text itself.  If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.  The response returned contains all of the same data points as a standard search response.\n\n```java\n// Create a SearchRequest with the term to request results for\nNaturalLanguageSearchRequest request = new NaturalLanguageSearchRequest(\"peanut butter\");\n\n// Add in additional parameters\nrequest.setResultsPerPage(5);\nrequest.setPage(1);\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Request results as an object\nSearchResponse response = constructor.naturalLanguageSearch(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.naturalLanguageSearchAsJSON(request, userInfo);\n```\n\n# Retrieving Browse Results\n\nTo retrieve browse results, you will need to create a `BrowseRequest`. When creating the `BrowseRequest` the filter name can be one of `collection_id`, `group_id`, or a facet name (i.e. Brand). In this request, you can also specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.\n\n```java\n// Create a BrowseRequest with the filter name and filter value to request results for\nBrowseRequest request = new BrowseRequest(\"group_id\", \"8193\");\n\n// Add in additional parameters\nrequest.setResultsPerPage(5);\nrequest.setPage(1);\nrequest.setGroupId(\"625\");r\nrequest.setSortBy(\"Price\");\nrequest.setSortAscending(true);\nrequest.getFacets().put(\"Brand\", Arrays.asList(\"Jif\"))\n\n// Add the following paramaters to request for hidden fields or facets\nrequest.getHiddenFields().add(\"hidden_price_field\");\nrequest.getHiddenFacets().add(\"hidden_brand_facet\");\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Add a variations map to request specific variation attributes as an array or object (optional)\nVariationsMap variationsMap = new VariationsMap();\nvariationsMap.setdType(VariationsMap.Dtypes.array);\nvariationsMap.addGroupByRule(\"variation\", \"data.variation_id\");\nvariationsMap.addValueRule(\"size\", VariationsMap.AggregationTypes.first, \"data.facets.size\");\nrequest.setVariationsMap(variationsMap);\n\n// Request results as an object\nBrowseResponse response = constructor.browse(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.browseAsJSON(request, userInfo);\n```\n\nIf you'd like to retrieve browse results asynchronously, the above code can be modified slightly to utilize a callback methodology:\n\n```java\nconstructor.browse(request, userInfo, new BrowseCallback() {\n  @Override\n  public void onFailure(final ConstructorException exception) {\n    // failure condition\n  }\n\n  @Override\n  public void onResponse(final BrowseResponse response) {\n    // success condition - data located within `response`\n  };\n});\n```\n\n# Retrieving Browse Results for Item ID's\n\nTo retrieve browse results for a supplied list of item ID's, you will need to create a `BrowseItemsRequest`. When creating the `BrowseItemsRequest` the `ids` parameter will be a list of item ID's. In this request, you can also specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.\n\n```java\n// Create a BrowseItemsRequest with the filter name and filter value to request results for\nBrowseItemsRequest request = new BrowseItemsRequest(Arrays.asList(\"t-shirt-xxl\"));\n\n// Add in additional parameters\nrequest.setResultsPerPage(5);\nrequest.setPage(1);\nrequest.setGroupId(\"625\");r\nrequest.setSortBy(\"Price\");\nrequest.setSortAscending(true);\nrequest.getFacets().put(\"Brand\", Arrays.asList(\"Jif\"))\n\n// Add the following paramaters to request for hidden fields or facets\nrequest.getHiddenFields().add(\"hidden_price_field\");\nrequest.getHiddenFacets().add(\"hidden_brand_facet\");\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Request results as an object\nBrowseResponse response = constructor.browseItems(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.browseItemsAsJSON(request, userInfo);\n```\n\nIf you'd like to retrieve browse items results asynchronously, the above code can be modified slightly to utilize a callback methodology:\n\n```java\nconstructor.browseItems(request, userInfo, new BrowseCallback() {\n  @Override\n  public void onFailure(final ConstructorException exception) {\n    // failure condition\n  }\n\n  @Override\n  public void onResponse(final BrowseResponse response) {\n    // success condition - data located within `response`\n  };\n});\n```\n\n# Retrieving Recommendation Results\n\nTo retrieve recommendation results, you will need to create a `RecommendationsRequest`. In this request, you can also specify the number of results you want and the items (given the ids) that you want to retrieve recommendations for. If the results are for a specific user, you can also create a `UserInfo` object, which will allow you to retrieve personalized results.\n\n```java\n// Create a RecommendationsRequest with the pod id to request results for\nRecommendationsRequest request = new RecommendationsRequest(\"pdp_complementary_items\");\n\n// Add in additional parameters\nrequest.setNumResults(5);\nrequest.setItemIds(Arrays.asList(\"9838172\"))\n\n// Create a UserInfo object with the session and unique device identifier (optional)\nUserInfo userInfo = new UserInfo(5, \"device-id-1123123\");\nuserInfo.setUserSegments(Arrays.asList(\"Desktop\", \"Chrome\"));\n\n// Add a variations map to request specific variation attributes as an array or object (optional)\nVariationsMap variationsMap = new VariationsMap();\nvariationsMap.setdType(VariationsMap.Dtypes.array);\nvariationsMap.addGroupByRule(\"variation\", \"data.variation_id\");\nvariationsMap.addValueRule(\"size\", VariationsMap.AggregationTypes.first, \"data.facets.size\");\nrequest.setVariationsMap(variationsMap);\n\n// Request results as an object\nRecommendationsResponse response = constructor.recommendations(request, userInfo);\n\n// Request results as a JSON string\nString response = constructor.recommendationsAsJSON(request, userInfo);\n```\n\n# Retrieving All Tasks\n\nTo retrieve all tasks, you will need to create a `AllTasksRequest`. In this request you can also specify the page and number of results per page. The page and number of results per page will default to 1 and 20 respectively.\n\n```java\n// Create a AllTasksRequest to request results for\nAllTasksRequest request = new AllTasksRequest();\n\n// Add in additional parameters\nrequest.setPage(2);\nrequest.setResultsPerPage(10);\n\n//Request all tasks as an object\nAllTasksResponse response = constructor.allTasks(request);\n\n//Request all tasks as a JSON string\nString response = constructor.allTasksAsJSON(request);\n```\n\n# Retrieving Task with task_id\n\nTo retrieve a specific task with a task_id, you will need to create a `TaskRequest`.\n\n```java\n// Create a TaskRequest with the task_id to retrieve\nTaskRequest request = new TaskRequest(\"12345\");\n\n//Request task as an object\nTask response = constructor.task(request);\n\n//Request task as a JSON string\nString response = constructor.taskAsJSON(request);\n```\n\n# Testing\n\nDownload the repository and run the following commands from `./constructorio-client`\n\n```bash\nmvn clean               # clean target directory\nmvn install             # installs dependencies\nmvn test                # run tests\nmvn spotless:check      # check lint\nmvn spotless:apply      # run lint\nmvn jacoco:report       # writes code coverage reports to ./target/site/jacoco\nmvn javadoc:javadoc     # generate docs\n```\n\n# Environment Variables\n\n```bash\nTEST_REQUEST_API_KEY    # autocomplete_key for the Client Library Integration Request (CRABS) Tests\nTEST_CATALOG_API_KEY    # autocomplete_key for the Client Library Integration Catalog Tests\nTEST_API_TOKEN          # API token for the tests\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructor-io%2Fconstructorio-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-java/lists"}