Search API

Search API is a powerful web search service that supports multiple search parameters and filtering options, capable of returning various types of results including web pages, images, and videos. This API is compatible with most return formats.

Basic Information

Endpoint: /api/web-search
Request Method: POST
Data Format: JSON
Character Encoding: UTF-8

Request Parameters

Required Parameters

Parameter	Type	Required	Description
query	string	Yes	Search keyword, cannot be empty

Optional Parameters

Parameter	Type	Required	Description
count	int	No	Number of results per page, default 10, maximum 50
offset	int	No	Result offset for pagination, default 0
freshness	string	No	Search web pages within specified time range, options: - noLimit: No limit (default) - oneDay: Within one day - oneWeek: Within one week - oneMonth: Within one month - oneYear: Within one year - YYYY-MM-DD..YYYY-MM-DD: Custom date range, e.g.: "2025-01-01..2025-04-06" - YYYY-MM-DD: Specific date, e.g.: "2025-04-06"

Response Parameters

Response Example

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "search keyword"
  },
  "webPages": {
    "webSearchUrl": "search URL",
    "totalEstimatedMatches": 1000,
    "value": [
      {
        "id": "result ID",
        "name": "webpage title",
        "url": "webpage URL",
        "displayUrl": "display URL",
        "snippet": "content snippet",
        "summary": "detailed summary",
        "siteName": "website name",
        "siteIcon": "website icon",
        "datePublished": "publish time",
        "dateLastCrawled": "crawl time",
        "cachedPageUrl": "cached page URL",
        "language": "webpage language",
        "isFamilyFriendly": true,
        "isNavigational": false,
        "deepLinks": [
          {
            "name": "deep link name",
            "url": "deep link URL",
            "snippet": "deep link snippet"
          }
        ]
      }
    ]
  }
}

Response Field Descriptions

SearchResponse

Field	Type	Description
_type	string	Response type, fixed as "SearchResponse"
queryContext	object	Query context information
webPages	object	Web search results
images	object	Image search results
videos	object	Video search results

WebSearchQueryContext

Field	Type	Description
originalQuery	string	Original search keyword

WebSearchWebPages

Field	Type	Description
webSearchUrl	string	Search URL
totalEstimatedMatches	int	Total number of matched web pages
value	array	Search result list
someResultsRemoved	boolean	Whether results were filtered for safety

WebPageValue

Field	Type	Description
id	string	Webpage sort ID
name	string	Webpage title
url	string	Webpage URL
displayUrl	string	Webpage display URL (url decoded format)
snippet	string	Brief description of webpage content
summary	string	Text summary of webpage content
siteName	string	Website name
siteIcon	string	Website icon
datePublished	string	Webpage publish time (UTC+8)
dateLastCrawled	string	Webpage crawl time (UTC+8)
cachedPageUrl	string	Cached page URL
language	string	Webpage language
isFamilyFriendly	boolean	Whether the page is family-friendly
isNavigational	boolean	Whether the page is navigational
deepLinks	array	Deep link list

WebSearchImages

Field	Type	Description
id	string	Image result ID
readLink	string	Image search link
webSearchUrl	string	Image search URL
isFamilyFriendly	boolean	Whether the content is family-friendly
value	array	Image result list

ImageValue

Field	Type	Description
webSearchUrl	string	Image search URL
name	string	Image name
thumbnailUrl	string	Thumbnail URL
datePublished	string	Publish time
contentUrl	string	Image content URL
hostPageUrl	string	Host page URL
contentSize	string	Content size
encodingFormat	string	Encoding format
hostPageDisplayUrl	string	Host page display URL
width	int	Image width
height	int	Image height
thumbnail	object	Thumbnail information

WebSearchVideos

Field	Type	Description
id	string	Video result ID
readLink	string	Video search link
webSearchUrl	string	Video search URL
isFamilyFriendly	boolean	Whether the content is family-friendly
scenario	string	Video scenario
value	array	Video result list

VideoValue

Field	Type	Description
webSearchUrl	string	Video search URL
name	string	Video name
description	string	Video description
thumbnailUrl	string	Thumbnail URL
publisher	array	Publisher information
creator	object	Creator information
contentUrl	string	Video content URL
hostPageUrl	string	Host page URL
encodingFormat	string	Encoding format
hostPageDisplayUrl	string	Host page display URL
width	int	Video width
height	int	Video height
duration	string	Video duration
motionThumbnailUrl	string	Motion thumbnail URL
embedHtml	string	Embed HTML
allowHttpsEmbed	boolean	Whether HTTPS embed is allowed
viewCount	int	View count
thumbnail	object	Thumbnail information
allowMobileEmbed	boolean	Whether mobile embed is allowed
isSuperfresh	boolean	Whether the content is super fresh
datePublished	string	Publish time

Error Codes

Error Code	Description
400	Invalid request parameters
401	Unauthorized
403	Forbidden
404	Resource not found
429	Too many requests
500	Internal server error

Notes

Timestamp Notes:
- datePublished: Actual webpage publish time
- dateLastCrawled: Webpage crawl time
- All timestamps are in UTC+8
Pagination Notes:
- Maximum 50 results per page
- Use offset parameter for pagination
- Recommended to request no more than 1000 results at once
Security Restrictions:
- Some results may be filtered for security reasons
- Check someResultsRemoved field to confirm if results were filtered
Performance Recommendations:
- Use freshness parameter to limit time range appropriately
- Use include/exclude parameters to narrow search scope
- Avoid frequent requests with the same keywords
Compatibility Notes:
- Some fields may vary slightly between different API versions, but core functionality remains consistent
- Please refer to specific API version documentation for detailed field descriptions

Usage Examples

Request Example

curl -X GET "https://platform.kuaisou.com/api/web-search?query=artificial+intelligence&count=10&offset=0"

Response Example

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "artificial intelligence"
  },
  "webPages": {
    "webSearchUrl": "https://platform.kuaisou.com/api/web-search?query=artificial+intelligence",
    "totalEstimatedMatches": 1000,
    "value": [
      {
        "id": "https://platform.kuaisou.com/api/v1/#WebPages.0",
        "name": "Artificial Intelligence - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
        "displayUrl": "en.wikipedia.org/wiki/Artificial_intelligence",
        "snippet": "Artificial intelligence (AI) is intelligence demonstrated by machines, as opposed to natural intelligence displayed by animals including humans.",
        "summary": "Artificial intelligence is a branch of computer science that aims to understand the nature of intelligence and produce machines that can simulate human-like intelligence."
      }
    ]
  }
}

Search API Python Demo

This document provides a simple example of how to call the Search API using Python.

Basic Call Example

import requests
import json

def search_web(query, api_key, count=10, summary=False):
    """
    Execute web search
    
    Parameters:
        query (str): Search keyword
        api_key (str): API key
        count (int): Number of results to return, default 10
        offset (int): Search page number
    """
    url = "https://platform.kuaisou.com/api/web-search"
    
    # Build request data
    payload = json.dumps({
        "query": query,
        "offset": 1,
        "count": count
    })
    
    # Set request headers
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    # Send request
    response = requests.post(url, headers=headers, data=payload)
    
    # Check response status
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Search request failed: {response.status_code} - {response.text}")

# Usage example
if __name__ == "__main__":
    # Set API key
    API_KEY = "sk-********"  # Replace with your API key
    
    try:
        # Execute search
        results = search_web(
            query="What is the meaning of life?",
            api_key=API_KEY,
            count=10,
            summary=True
        )
        
        # Print results
        print(json.dumps(results, indent=2, ensure_ascii=False))
        
    except Exception as e:
        print(f"Error occurred: {str(e)}")

More Parameter Examples

# Search with time range
results = search_web(
    query="Artificial Intelligence",
    api_key=API_KEY,
    count=20,
    offset=1,
    freshness="oneWeek"  # Results from the past week
)

# Search within specific websites
results = search_web(
    query="Python Tutorial",
    api_key=API_KEY,
    count=15,
    offset=1
)

# Search with custom date range
results = search_web(
    query="News",
    api_key=API_KEY,
    count=10,
    summary=True,
    freshness="2024-01-01..2024-03-20"  # Custom date range
)

Basic Information​

Request Parameters​

Required Parameters​

Optional Parameters​

Response Parameters​

Response Example​

Response Field Descriptions​

SearchResponse​

WebSearchQueryContext​

WebSearchWebPages​

WebPageValue​

WebSearchImages​

ImageValue​

WebSearchVideos​

VideoValue​

Error Codes​

Notes​

Usage Examples​

Request Example​

Response Example​

Search API Python Demo

Basic Call Example​

More Parameter Examples​

Basic Information

Request Parameters

Required Parameters

Optional Parameters

Response Parameters

Response Example

Response Field Descriptions

SearchResponse

WebSearchQueryContext

WebSearchWebPages

WebPageValue

WebSearchImages

ImageValue

WebSearchVideos

VideoValue

Error Codes

Notes

Usage Examples

Request Example

Response Example

Basic Call Example

More Parameter Examples