Since its release in January, the Maven Central website (http://search.maven.org) has provided Apache Maven users with:

• Search functionality that allows one to quickly track down artifacts and their dependency details when trying to resolve build problems.
• Browse functionality that aids in discovery of new artifacts to use in projects.

In the intervening months, Sonatype has focused its efforts on improving the usability of the Maven Central user interface in the hopes of making it the first place users look when trying to find an artifact.  Recently, users who have reaped the benefits of using the Maven Central website have asked about interacting programmatically with the search functionality.

If you pay attention to your web browser’s address bar when conducting searches on Maven Central, you can already see that a REST-style API exists.  For example, searching for “guice” from the main search box results in the following URL being generated (the following URL’s are NOT URL-encoded for the sake of readability):

• http://search.maven.org/#search|ga|1|guice

Translating the search request into English, that URL requests a basic search for any artifact (irrespective of version) containing the word “guice” in either the groupId or artifactId, returning only the first page of results.  Each row of the results shows the latest version of the artifact and the date the artifact was last updated as well as any classifiers associated with the artifact.

You can build up the complete library of search requests simply by paying attention to your web browser’s address field as you use the Maven Central website.  For the sake of convenience, we’ve collected all the URLs that make up Maven Central’s search API in a document available here.

Sadly, these URL’s are still only useful when requesting them via web browser.  They are links that can be bookmarked or e-mailed, but they do NOT work when using a non-browser agent like wget or curl.  The Maven Central user interface is essentially a browser-based application that uses Javascript to make asynchronous requests to yet another set of URL’s.  Once you make a request that looks like the URL above, the browser fires off the actual request to another Maven Central URL responsible for conducting the search and returning results that are formatted by the browser.

The sample request above, when converted to an actual Maven Central search request, looks like this:

• http://search.maven.org/solrsearch/select?q=guice&rows=20&wt=json

The actual text of your query goes in the appropriately named “q” parameter, the “rows” parameter restricts the results to a smaller number than the full result set, and the “wt” parameter can be either “xml” or “json,” depending on how your application prefers to handle results.

Some useful examples appear below.  Again, please refer to the API Guide for a complete listing:

• Fully-qualified classname search – http://search.maven.org/solrsearch/select?q=fc:”org.specs.runner.JUnit”&rows=20&wt=json
• GroupId and artifactId search that returns all available artifact versions – http://search.maven.org/solrsearch/select?q=g:”org.apache.maven.indexer”+AND+a:”maven-indexer”&rows=20&core=gav
• SHA1 search (you would need to pre-calculate the SHA1 before sending the request to Maven Central) – http://search.maven.org/solrsearch/select?q=1:”2d3c16092663da9041b171b8d3627cbafa8f0cb1″&rows=20&wt=json

In an upcoming post, I’ll describe the architecture behind Maven Central that makes all this functionality possible.