SDK quick start

Get a sub-account AccessKey

To reuse an existing AccessKey, grant the AliyunIQSFullAccess permission to the sub-account.

Create a RAM user and grant permissions

Create a RAM user and grant permissions

Create an AccessKey

Create an AccessKey for a RAM user

API list

Python SDK

Install the SDK

pip3 install alibabacloud_iqs20241111==1.7.3

Sample code (synchronous)

This example shows how to synchronously call the unified_search method.

import os

from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> Client:
        config = open_api_models.Config(
            # TODO: Replace with your AccessKey ID and AccessKey Secret. Loading credentials from environment variables is recommended.
            access_key_id='$YOUR_ACCESS_KEY',
            access_key_secret='$YOUR_ACCESS_SECRET'
        )
        config.endpoint = f'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    @staticmethod
    def main() -> None:
        client = Sample.create_client()
        advancedParams = {
            "startPublishedDate": "2025-10-01",
            "endPublishedDate": "2025-10-10"
        }
        run_instances_request = models.UnifiedSearchRequest(
            body=models.UnifiedSearchInput(
                query='Hangzhou cuisine',
                time_range='NoLimit',
                contents=models.RequestContents(
                    summary=False,
                    main_text=True,
                ),
                advanced_params=advancedParams
            )
        )
        try:
            response = client.unified_search(run_instances_request)
            print(
                f"api success, request_id:{response.body.request_id}, size :{len(response.body.page_items)}, server_cost:{response.body.search_information.search_time}")
            if len(response.body.scene_items) > 0:
                print(f"scene_items:{response.body.scene_items[0]}")
            for index, item in enumerate(response.body.page_items):
                print(f"{index}. {'-' * 20}")
                print(f"title:{item.title}")
                print(f"snippet:{item.snippet}")
                print(f"summary:{item.summary}")
                print(f"published_time:{item.published_time}")
                print(f"link:{item.link}")
                print(f"rerank_score:{item.rerank_score}")

        except TeaException as e:
            code = e.code
            request_id = e.data.get("requestId")
            message = e.data.get("message")
            print(f"api exception, requestId:{request_id}, code:{code}, message:{message}")


if __name__ == '__main__':
    Sample.main()

Sample code (asynchronous)

import asyncio
import os
import time

from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> Client:
        config = open_api_models.Config(
            # This sample loads credentials from the ALIYUN_ACCESS_KEY and ALIYUN_ACCESS_SECRET environment variables.
            access_key_id=os.environ.get('ALIYUN_ACCESS_KEY'),
            access_key_secret=os.environ.get('ALIYUN_ACCESS_SECRET')

        )
        config.endpoint = f'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    @staticmethod
    async def main_async() -> None:
        start = time.time()
        client = Sample.create_client()
        run_instances_request = models.UnifiedSearchRequest(
            body=models.UnifiedSearchInput(
                query='Hangzhou cuisine',
                time_range='NoLimit',
                contents=models.RequestContents(
                    # Note: The summary feature is billed separately.                
                    summary=True,
                    main_text=True,
                )
            )
        )
        try:
            # Use the asynchronous method
            response = await client.unified_search_async(run_instances_request)
            print(
                f"api success, request_id:{response.body.request_id}, size :{len(response.body.page_items)}, server_cost:{response.body.search_information.search_time}")
            if len(response.body.scene_items) > 0:
                print(f"scene_items:{response.body.scene_items[0]}")
            for index, item in enumerate(response.body.page_items):
                print(f"{index}. {'-' * 20}")
                print(f"title:{item.title}")
                print(f"snippet:{item.snippet}")
                print(f"summary:{item.summary}")
                print(f"published_time:{item.published_time}")
                print(f"link:{item.link}")
                print(f"rerank_score:{item.rerank_score}")
        except TeaException as e:
            code = e.code
            request_id = e.data.get("requestId")
            message = e.data.get("message")
            print(f"api exception, requestId:{request_id}, code:{code}, message:{message}")

if __name__ == '__main__':
    asyncio.run(Sample.main_async())

Java SDK

Install the SDK

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>iqs20241111</artifactId>
    <version>1.7.3</version>
</dependency>

Sample code

package com.aliyun.iqs.example;

import com.aliyun.iqs20241111.Client;
import com.aliyun.iqs20241111.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.util.HashMap;
import java.util.Map;

public class UnifiedSearchExample {
    public static void main(String[] args) throws Exception {
        Client client = initClient();
        invoke(client, "Hangzhou cuisine", "NoLimit");
    }

    private static Client initClient() throws Exception {
        // TODO: Replace with your AccessKey ID and AccessKey Secret. We recommend loading them from environment variables.
        String accessKeyId = "$YOUR_ACCESS_KEY";
        String accessKeySecret = "$YOUR_ACCESS_SECRET";
        
        Config config = new Config()
            .setAccessKeyId(accessKeyId)
            .setAccessKeySecret(accessKeySecret);

        config.setEndpoint("iqs.cn-zhangjiakou.aliyuncs.com");
        return new Client(config);
    }

    private static void invoke(Client client, String query, String timeRange) {
        UnifiedSearchInput input = new UnifiedSearchInput();
        input.setQuery(query);
        input.setTimeRange(timeRange);
        
        // The date range parameters are optional.
        Map<String, String> advancedParams = new HashMap<>();
        advancedParams.put("startPublishedDate","2025-10-01");
        advancedParams.put("endPublishedDate","2025-10-10");
        input.setAdvancedParams(advancedParams);

        // Note: The summary feature is billed separately.
        RequestContents requestContents = new RequestContents().setSummary(true).setMainText(true);
        input.setContents(requestContents);
        UnifiedSearchRequest request = new UnifiedSearchRequest().setBody(input);

        try {
            UnifiedSearchResponse response = client.unifiedSearch(request);
            UnifiedSearchOutput result = response.getBody();

            printOutput(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static void printOutput(UnifiedSearchOutput output) {
        // Use GsonBuilder to create a pretty-printing Gson instance.
        Gson gson = new GsonBuilder()
            .setPrettyPrinting()
            .disableHtmlEscaping()
            .create();

        // Print the formatted JSON.
        String prettyJson = gson.toJson(output);
        System.out.println(prettyJson);
    }
}

Go SDK

Install the SDK

require (
  github.com/alibabacloud-go/iqs-20241111 v1.7.3
  github.com/alibabacloud-go/darabonba-openapi/v2 v2.0.10
)

Sample code

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	iqs20241111 "github.com/alibabacloud-go/iqs-20241111/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"log"
)

const endpointURL = "iqs.cn-zhangjiakou.aliyuncs.com"

func createClient() (*iqs20241111.Client, error) {
	// TODO: Replace with your AccessKey ID and AccessKey Secret.
	accessKeyID := "$YOUR_ACCESS_KEY"
	accessKeySecret := "$YOUR_ACCESS_SECRET"

	if accessKeyID == "" || accessKeySecret == "" {
		return nil, fmt.Errorf("ACCESS_KEY or ACCESS_SECRET environment variable is not set")
	}

	config := &openapi.Config{
		AccessKeyId:     tea.String(accessKeyID),
		AccessKeySecret: tea.String(accessKeySecret),
		Endpoint:        tea.String(endpointURL),
	}

	return iqs20241111.NewClient(config)
}

func runGenericSearch(client *iqs20241111.Client) error {
	body := &iqs20241111.UnifiedSearchInput{
		Query:     tea.String("Hangzhou cuisine"),
		TimeRange: tea.String("NoLimit"),
		// Note: The summary feature is billed separately.
		Contents: &iqs20241111.RequestContents{
			Summary:  tea.Bool(true),
			MainText: tea.Bool(true),
		},
	}
	request := &iqs20241111.UnifiedSearchRequest{
		body,
	}
	runtime := &util.RuntimeOptions{}

	resp, err := client.UnifiedSearchWithOptions(request, nil, runtime)
	if err != nil {
		return fmt.Errorf("generic search failed: %w", err)
	}

	fmt.Printf("[%s] response: %s\n", *resp.Body.RequestId, resp.Body)
	return nil
}

func main() {
	client, err := createClient()
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	if err := runGenericSearch(client); err != nil {
		log.Fatalf("Error running generic search: %v", err)
	}
}

Node.js SDK

Install the SDK

npm install @alicloud/iqs20241111@1.7.3

Sample code

import * as $OpenApi from '@alicloud/openapi-client';
import * as $IQS20241111 from '@alicloud/iqs20241111';

class Sample {
  static createClient(): $IQS20241111.default {
    const config = new $OpenApi.Config({
      // This sample loads credentials from the ALIYUN_ACCESS_KEY and ALIYUN_ACCESS_SECRET environment variables.
      accessKeyId: process.env.ALIYUN_ACCESS_KEY,
      accessKeySecret: process.env.ALIYUN_ACCESS_SECRET,
    });
    config.endpoint = 'iqs.cn-zhangjiakou.aliyuncs.com';
    return new $IQS20241111.default(config);
  }

  static async main(): Promise<void> {
    const client = Sample.createClient();
    
    const advancedParams = {
      startPublishedDate: '2025-10-01',
      endPublishedDate: '2025-10-10',
    };

    const runInstancesRequest = new $IQS20241111.UnifiedSearchRequest({
      body: new $IQS20241111.UnifiedSearchInput({
        query: 'Hangzhou cuisine',
        timeRange: 'NoLimit',
        contents: new $IQS20241111.RequestContents({
          // Note: The summary feature is billed separately.
          summary: true,
          mainText: true,
        }),
        advancedParams: advancedParams,
      }),
    });

    try {
      const response = await client.unifiedSearch(runInstancesRequest);
      
      if (!response.body) {
        console.error('Response body is empty');
        return;
      }

      console.log(
        `api success, request_id:${response.body.requestId}, size:${response.body.pageItems?.length || 0}, server_cost:${response.body.searchInformation?.searchTime}`
      );

      if (response.body.sceneItems && response.body.sceneItems.length > 0) {
        console.log(`scene_items:${JSON.stringify(response.body.sceneItems[0])}`);
      }

      response.body.pageItems?.forEach((item: any, index: number) => {
        console.log(`${index}. ${'-'.repeat(20)}`);
        console.log(`title:${item.title}`);
        console.log(`snippet:${item.snippet}`);
        console.log(`summary:${item.summary}`);
        console.log(`published_time:${item.publishedTime}`);
        console.log(`link:${item.link}`);
        console.log(`rerank_score:${item.rerankScore}`);
      });
    } catch (error: any) {
      const code = error.code;
      const requestId = error.data?.requestId;
      const message = error.message;
      console.error(`api exception, requestId:${requestId}, code:${code}, message:${message}`);
    }
  }
}

Sample.main();