{"id":42186728,"url":"https://github.com/adaptiverecognition/java-carmen-cloud-client","last_synced_at":"2026-01-26T22:27:57.476Z","repository":{"id":175256110,"uuid":"653557282","full_name":"adaptiverecognition/java-carmen-cloud-client","owner":"adaptiverecognition","description":"The Carmen Cloud Client provides a convenient way to leverage the features of the Adaptive Recognition's Carmen Cloud platform.","archived":false,"fork":false,"pushed_at":"2025-11-28T18:10:33.000Z","size":126,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-29T02:41:12.063Z","etag":null,"topics":["anpr","carmen","client","cloud","mmr","vehicle-recognition"],"latest_commit_sha":null,"homepage":"https://carmencloud.com","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adaptiverecognition.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-14T09:27:12.000Z","updated_at":"2025-11-28T18:11:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"3f6a3122-ac5c-49b8-9e30-b9921d375023","html_url":"https://github.com/adaptiverecognition/java-carmen-cloud-client","commit_stats":null,"previous_names":["adaptiverecognition/java-carmen-cloud-client","adaptiverecognition/carmen-cloud-client"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/adaptiverecognition/java-carmen-cloud-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptiverecognition%2Fjava-carmen-cloud-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptiverecognition%2Fjava-carmen-cloud-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptiverecognition%2Fjava-carmen-cloud-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptiverecognition%2Fjava-carmen-cloud-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptiverecognition","download_url":"https://codeload.github.com/adaptiverecognition/java-carmen-cloud-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptiverecognition%2Fjava-carmen-cloud-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28789739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["anpr","carmen","client","cloud","mmr","vehicle-recognition"],"created_at":"2026-01-26T22:27:56.851Z","updated_at":"2026-01-26T22:27:57.468Z","avatar_url":"https://github.com/adaptiverecognition.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carmen Cloud Client\n\nThe Carmen Cloud Client provides a convenient way to leverage the features of the Adaptive Recognition's Carmen Cloud platform. With the Carmen Cloud platform, you can extract the needed information from the uploaded images, such as license plate numbers, vehicle make and model, and vehicle identification numbers (VINs).\n\n# Building the client\n\nBefore proceeding, install a [JDK](https://jdk.java.net/archive/) (must be Java 17 or later) and [Apache Maven](https://maven.apache.org/install.html).\n\nEnsure `JAVA_HOME` is set correctly and the `mvn` executable is available on your PATH.\n\nRun the following command in a terminal/console.\n\n```bash\nmvn clean install\n```\n\nThis compiles the client into your local maven repository.\n\n# Using the client\n\nTo depend on this project in Apache Maven, add the following to your pom.xml file. (Always use the latest version if possible.)\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.adaptiverecognition\u003c/groupId\u003e\n        \u003cartifactId\u003ecarmen-cloud-client\u003c/artifactId\u003e\n        \u003cversion\u003e4.5.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nFor more information on managing dependencies with Maven and publishing artifacts, see:\n\n- [https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html)\n- [http://central.sonatype.org/pages/ossrh-guide.html](http://central.sonatype.org/pages/ossrh-guide.html)\n\n# Developer Guide\n\n## Creating a client\n\nTo create a client, use the client builder. You can obtain an instance of the builder via a static factory method located in the `CarmenCloudClientBuilder` class:\n\n```java\nVehicleClient.VehicleClientBuilder vehicleClientBuilder = CarmenCloudClientBuilder.vehicleClientBuilder();\n```\n\nor\n\n```java\nTransportClient.TransportClientBuilder transportClientBuilder = CarmenCloudClientBuilder.transportClientBuilder();\n```\n\nThe builder exposes many configuration methods that can be chained to configure an API client. Here's a simple example that sets a few optional configuration options and then builds the vehicle API client.\n\n```java\nVehicleClient.VehicleClientBuilder vehicleClientBuilder = CarmenCloudClientBuilder.vehicleClientBuilder();\nVehicleClient client = vehicleClientBuilder\n    .endpoint(\"https://api.carmencloud.com\")\n    .apiKey(\"*****\")\n    .responseTimeout(10_000L)\n    .retry(vehicleClientBuilder.defaultRetry())\n    .disableImageResizing(true)\n    .enableWideRangeAnalysis(true)\n    .build();\n```\n\n## API key\n\nAn API key must be provided for the client builder. After you obtain your API key on the [Cloud Console](https://carmencloud.com/console), it can be set via the client builder. It is recommended to treat the API key as sensitive and not hard-code it in your source code.\n\n```java\nVehicleClient client = CarmenCloudClientBuilder.vehicleClientBuilder()\n    .apiKey(\"YOUR-API-KEY-GOES-HERE\")\n    .build();\n```\n\nAfter it is configured, the API key is sent with every request made to the API endpoint via the `X-Api-Key` header.\n\n## Making requests\n\nAfter a client is configured and created, you can make a request to the API endpoint. The request class has setters for any parameters and payload that are defined in the API. The response class exposes getters for the modelled payload.\n\n```java\nVehicleClient client = CarmenCloudClientBuilder.vehicleClientBuilder()\n    .endpoint(\"https://api.carmencloud.com\")\n    .apiKey(\"*****\").build();\nVehicleResult result = client.search(new VehicleRequest()\n\t.region(\"eur\")\n\t.location(\"HUN\")\n\t.services(VehicleRequest.Service.ANPR,VehicleRequest.Service.MMR)\n\t.image(new FileInputStream(new File(\"\u003cPATH-OF-INPUT-IMAGE\u003e\")).readAllBytes(), \"test-image.jpg\"));\n```\n\n## Making requests asynchronously\n\nThe asynchronous methods of the clients returns `java.util.concurrent.CompletableFuture`.\n\n```java\nVehicleClient client = CarmenCloudClientBuilder.vehicleClientBuilder()\n    .endpoint(\"https://api.carmencloud.com\")\n    .apiKey(\"*****\").build();\nVehicleResult result = client.searchAsync(new VehicleRequest()\n\t.region(\"eur\")\n\t.location(\"HUN\")\n\t.services(VehicleRequest.Service.ANPR,VehicleRequest.Service.MMR)\n\t.image(new FileInputStream(new File(\"\u003cPATH-OF-INPUT-IMAGE\u003e\")).readAllBytes(), \"test-image.jpg\"))\n.whenComplete((result, throwable) -\u003e {\n    if (throwable != null) {\n        // handling error\n    }\n    else {\n        // handling the result\n    }\n});\n```\n\n## Exception Handling\n\nThe API clients are using the Spring Reactive WebClient to make requests to the API endpoints, so the service exceptions and client exceptions can be handled separately. Client exceptions will be a subtype of `org.springframework.web.reactive.function.client.WebClientRequestException`, service exceptions will be a subtype of `CarmenCloudException`.\n\n```java\ntry {\n    client.search(...);\n} catch(WebClientRequestException e) {\n    // handling client exceptions raised by the inner WebClient\n} catch(CarmenCloudException e) {\n    int statusCode = e.getStatusCode();\n    // handling service exceptions\n}\n```\n\n## Retries\n\nOut of the box, the generated client retries on throttling and server errors (HTTP status code 429 and 500). If a different retry policy is desired, a custom one can be set via the client builder.\n\nThe easiest way to create a custom retry policy is to use the `reactor.util.retry.Retry` class. It provides a declarative API to specify when and how to retry.\n\n```java\n/**\n * The policy below will retry if the cause of the failed request matches any of the exceptions\n * given OR if the HTTP response from the service has one of the provided status codes.\n */\nVehicleClient vehicleClient = CarmenCloudClientBuilder.vehicleClientBuilder()\n    .endpoint(\"https://api.carmencloud.com\")\n    .apiKey(\"*****\")\n    .responseTimeout(10_000L)\n    .retry(Retry.backoff(3 /* retry count */, Duration.ofSeconds(1)).doBeforeRetry((rs) -\u003e {\n          int retryNumber = (int) rs.totalRetriesInARow() + 1;\n          // ...\n        }).filter(throwable -\u003e {\n          if (throwable instanceof WebClientRequestException) {\n            return true;\n          }\n          if (throwable instanceof CarmenCloudException) {\n            int statusCode = ((CarmenCloudException) throwable).getStatusCode();\n            return statusCode == 429 || statusCode \u003e= 500;\n          }\n          return false;\n        })).build();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptiverecognition%2Fjava-carmen-cloud-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptiverecognition%2Fjava-carmen-cloud-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptiverecognition%2Fjava-carmen-cloud-client/lists"}