GetClusters

The GetClusters method is used to return facets which organize search results into groups based on categories such as: source types, subjects, authors, publications, companies, geography, location and content providers that are associated with a particular database(s) for a given query.

To test this method with your EIT profile, visit the EBSCOhost API GetClusters method page.

Input Parameters

Hide | Back to Top

These are the input parameters for both the REST and SOAP protocols of the EBSCOhost API GetClusters method. To see more information on either the REST or SOAP protocol with the EBSCOhost API, see:

The REST and SOAP protocols will return the same results, but the parameter names are different. Parameter names for the REST protocol are listed under the "REST" column, and parameter names for the SOAP protocol are listed under the "SOAP" column.

REST
SOAP
Description
Required
Values
prof Profile* The profile used for authentication. This must be an EIT enabled profile. Required if using profile authentication. -
pwd Password* The password used for profile authentication. Required if using profile authentication. -
authType AuthType* Indicates if using IP Authentication or Profile Authentication.

Default: profile
No profile,
ip
ipprof IpProfile* The profile used for authentication. Required if using IP authentication. -
- IpAddress* The IP address used for authentication. Required if using IP authentication. -
query Query Terms to be searched on. Yes -
db Databases Database(s) to perform the search on. Yes -
* When using the SOAP API, these items must be in the AuthorizationHeader of the request. See Making Requests with SOAP for more information on how to form the AuthorizationHeader.

Output Format

Hide | Back to Top

This is the expected output of the GetClusters function:

<?xml version="1.0"?>
<clusterResponse>
   <ClusterCategory ID="xs:string"  Tag="xs:string" >
      <Cluster>
      </Cluster>
   </ClusterCategory>
</clusterResponse>

Viewing: Simplified Response | Real Response

Upon success, the first node returned should be the <clusterResponse> node (note: in SOAP, this node is contained within the Envelope/Body/GetClustersResponse node). If there was an error, then the first node returned would be the <Fault> node.

If the query was sucessful and returned results, the next node should be the <ClusterCategory> node. This node contains all of the different cluster categories available for this database It has two attributes: 'ID', which is the text description of the cluster category, and 'Tag', which is a search tag that can be used to format a query (See Formatting Queries). Each <ClusterCategory> node contains many <Cluster> nodes. Each <Cluster> node contains the name of the cluster.

REST Sample

Hide | Back to Top

This is a sample of the Search method using the REST protocol.

Call:
http://eit.ebscohost.com/Services/SearchService.asmx/GetClusters?
	prof=[Your EIT Profile ID]
	&pwd=[Your Profile Password]
	&query=[Your Search Query]
	&db=[Authority Database to Search]
Response:
<?xml version="1.0">
<clusterResponse>
   <ClusterCategory ID="xs:string" Tag="xs:string">
      <Cluster> 
		<!-- Cluster Name -->
	  </Cluster> 
   <ClusterCategory>
</clusterResponse>

SOAP Sample

Hide | Back to Top

This is a sample of the Search methods output using the SOAP protocol.

Call:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" >
  <soap:Header>
    <eit:AuthorizationHeader soap:mustUnderstand="1" xmlns:eit="http://epnet.com/webservices/SearchService/2007/07/">
      <eit:Profile>[Your EIT Profile ID]</eit:Profile>
      <eit:Password>[Your  Profile Password]</eit:Password>
    </eit:AuthorizationHeader>
  </soap:Header>
  <soap:Body>
    <eit:GetClusters xmlns:eit="http://epnet.com/webservices/SearchService/2007/07/">
      <eit:ClusterSearchRequest>
        <eit:Query>[Search Query]</eit:Query>
        <eit:Databases>[Database(s) to Retrieve Clusters]</eit:Databases>
      </eit:ClusterSearchRequest>
    </eit:GetClusters>
  </soap:Body>
</soap:Envelope>
				


Response:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetClustersReponse xmlns="http://epnet.com/webservices/SearchService/2007/07/">
      <clusterResponse>
        <ClusterCategory ID="xs:string" Tag="xs:string">
          <Cluster> 
	 	    <!-- Cluster Name -->
	      </Cluster> 
        <ClusterCategory>
      </clusterResponse>
    </GetClustersReponse>
  </soap:Body>
</soap:Envelope>