Xiaohongshu Pgy APIs - KOL Search (V1)
Search for KOLs using various filters.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | Yes | User authentication token. |
searchType | query | string | No | Search criteria type. Available Values: - NICKNAME: Search by nickname- NOTE: Search by note content |
keyword | query | string | No | Search keyword. |
page | query | integer | No | Page number. |
fansNumberLower | query | integer | No | Minimum number of fans. |
fansNumberUpper | query | integer | No | Maximum number of fans. |
fansAge | query | string | No | Target fans age group. Available Values: - ALL: All ages- LT_18: Under 18- AGE_18_24: 18 to 24- AGE_25_34: 25 to 34- AGE_35_44: 35 to 44- GT_44: Above 44 |
fansGender | query | string | No | Target fans gender. Available Values: - ALL: All genders- MALE_HIGH: Mainly Male- FE_MALE_HIGH: Mainly Female |
gender | query | string | No | KOL's gender. Available Values: - ALL: All genders- MALE: Male- FEMALE: Female |
contentTag | query | string | No | Content categories, separated by commas. |
Code Samples
💡 Environment Note
Default samples use https://api.justoneapi.com (prod-global). For users in Mainland China, it is recommended to replace it with http://47.117.133.51:30015 (prod-cn) for better performance. See Environment Guide.
bash
# Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
curl -X GET "https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY"text
I want to use the "KOL Search (V1)" API from Just One API.
API Endpoint: https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1
HTTP Method: GET
Authentication: Append "?token=YOUR_API_KEY" to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/xiaohongshu-pgy-apis/kol-search-v1-en.json
Parameters:
- token (query): User authentication token. (Required)
- searchType (query): Search criteria type.
Available Values:
- `NICKNAME`: Search by nickname
- `NOTE`: Search by note content
- keyword (query): Search keyword.
- page (query): Page number.
- fansNumberLower (query): Minimum number of fans.
- fansNumberUpper (query): Maximum number of fans.
- fansAge (query): Target fans age group.
Available Values:
- `ALL`: All ages
- `LT_18`: Under 18
- `AGE_18_24`: 18 to 24
- `AGE_25_34`: 25 to 34
- `AGE_35_44`: 35 to 44
- `GT_44`: Above 44
- fansGender (query): Target fans gender.
Available Values:
- `ALL`: All genders
- `MALE_HIGH`: Mainly Male
- `FE_MALE_HIGH`: Mainly Female
- gender (query): KOL's gender.
Available Values:
- `ALL`: All genders
- `MALE`: Male
- `FEMALE`: Female
- contentTag (query): Content categories, separated by commas.
Return format: JSON
Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set request timeout to at least 60 seconds.
3. Business Code Reference:
- 0: Success
- 100: Invalid or Inactive Token
- 301: Collection Failed. Please Retry.
- 302: Rate Limit Exceeded
- 303: Daily Quota Exceeded
- 400: Invalid Parameters
- 500: Internal Server Error
- 600: Permission Denied
- 601: Insufficient Balance
Please help me write a script in my preferred programming language to call this API and handle the response.python
# Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
import requests
url = "https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY"
response = requests.get(url)
print(response.json())js
// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
const response = await fetch("https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY", {
method: "GET"
});
const data = await response.json();
console.log(data);java
// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}go
// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
client := &http.Client{}
url := "https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY"
req, _ := http.NewRequest("GET", url, nil)
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}php
// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.justoneapi.com/api/xiaohongshu-pgy/api/solar/cooperator/blogger/v2/v1?token=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
curl_close($ch);
echo $response;Responses
json
{
"code": 0,
"data": {
"kols": [
{
"userId": "5fe83d6600000000010078c7",
"valid": 1,
"headPhoto": "https://sns-avatar-qc.xhscdn.com/avatar/1040g2jo31sdek3jr68kg5nv87lj08u676pictl8?imageView2/2/w/120/...",
"name": "鹤竹zzzz",
"redId": "1032482443",
"location": "天津",
"homePageDisplay": 1,
"travelAreaList": null,
"type": [],
"personalTags": null,
"fansCount": 0,
"likeCollectCountInfo": null,
"businessNoteCount": 0,
"totalNoteCount": null,
"recommend": null,
"picturePrice": 158,
"videoPrice": 9999999,
"lowerPrice": 158,
"userType": 2,
"showPrice": true,
"pictureState": 1,
"videoState": 1,
"isCollect": false,
"cooperateState": 1,
"pictureInCart": null,
"videoInCart": null,
"note": null,
"live": null,
"cps": null,
"noteSign": null,
"liveSign": null,
"goodRecommendPermission": null,
"cpc": null,
"pictureCpcBasePrice": "0",
"pictureCpcPerPrice": "0",
"pictureCpcEstimateNum": null,
"videoCpcState": null,
"videoCpcBasePrice": "0",
"videoCpcPerPrice": "0",
"videoCpcEstimateNum": null,
"pictureCpcInCart": null,
"videoCpcInCart": null,
"contentTags": [
{
"taxonomy1Tag": "兴趣爱好",
"taxonomy2Tags": [
"阅读"
]
}
],
"featureTags": null,
"industryTag": null,
"gender": "女",
"picPriceRemind": null,
"videoPriceRemind": null,
"currentLevel": 2,
"nextLevel": -1,
"priceState": 1,
"resemblance": true,
"noteList": [
{
"noteId": "69a976c3000000000e00e3ff",
"noteType": 1,
"imageUrl": "http://ci.xiaohongshu.com/1040g00831tb5h0ullmqg5nv87lj08u67r2ncvv8?imageView2/2/w/540/format/jpg/q/7...",
"featureTags": [],
"contentTag": "文化艺术",
"industryTags": null,
"bind": false
}
],
"tradeType": null,
"clickMidNum": 7972,
"clickMidNumMcn": 0,
"interMidNum": 1138,
"fansNum": 4544,
"matchNoteNumber": 0,
"authorityList": null,
"processingAuthorities": null,
"pictureShowState": null,
"videoShowState": null,
"classifyCode": 1,
"predictiveExposure": 0,
"efficiencyValidUser": 0,
"pictureReadCost": "0.31",
"videoReadCost": "0.00",
"pictureClickMidNum": 14139,
"pictureInterMidNum": 1957,
"videoClickMidNum": 0,
"videoFinishRate": 0,
"videoInterMidNum": 0,
"fans30GrowthRate": 130.9,
"fans30GrowthNum": 0,
"nextPicturePrice": null,
"nextVideoPrice": null,
"fansRiseNum": null,
"fansEngageNum": null,
"overflowNum": null,
"newHighQuality": 0,
"isIndustryRecommend": false,
"picturePriceGtZero": true,
"videoPriceGtZero": true,
"lowActive": true,
"fansActiveIn28dLv": 98.8,
"fansEngageNum30dLv": 43,
"hundredLikePercent30": 80,
"thousandLikePercent30": 60,
"pictureHundredLikePercent30": 80,
"pictureThousandLikePercent30": 60,
"videoHundredLikePercent30": 0,
"videoThousandLikePercent30": 0,
"cooperType": 1,
"buyerType": 2,
"promiseImpNum": "0",
"kolType": 0,
"showPromiseTag": 0,
"activityList": [],
"controlState": 0,
"clothingIndustryPrice": {
"bizType": null,
"industryId": 0,
"picturePrice": 0,
"pictureState": 0,
"videoPrice": 0,
"videoState": 0
},
"fbState": 0,
"forecastReadUvLower": 0,
"forecastReadUvUpper": 0,
"forecastGroupCoverRateLower": 0,
"forecastGroupCoverRateUpper": 0,
"intentionInfo": {
"intentionText": "",
"intentionType": 0
},
"seedAndHarcest": null,
"liveImg": null,
"liveId": null,
"liveGMV": null,
"isStar": null,
"top2CategoryList": null,
"hasBuyerAuth": true,
"sellerRealIncomeAmt90d": 0,
"estimatePictureCpm": 5.26,
"estimatePictureCpmCompare": 97.8,
"estimateVideoCpm": 0,
"estimateVideoCpmCompare": 47,
"estimatePictureEngageCost": 0.07,
"estimatePictureEngageCostCompare": 97.8,
"estimateVideoEngageCost": 0,
"estimateVideoEngageCostCompare": 47,
"inviteReply48hNumRatio": 31.3,
"recommendReason": null,
"kolHeadLabel": 0,
"accumCoopImpMedinNum30d": 0,
"estimateCpuv30d": 0,
"accumPicCommonImpMedinNum30d": 30032,
"accumVideoCommonImpMedinNum30d": 0,
"accumCommonImpMedinNum30d": 22663,
"marketTarget": null,
"readMidCoop30": 0,
"interMidCoop30": 0,
"coopNoteNum30d": 0,
"specialIndustryLimit": false,
"kliveCnt30d": 0,
"avgAgmv90d": 0,
"avgLiveViewerNum": 0,
"algoRecommendReasons": null,
"mcpuvNum30d": 0,
"mengagementNumMcn": 0,
"mengagementNum": 1278,
"mEngagementNum": 1278,
"mEngagementNumMcn": 0,
"mCpuvNum30d": 0
}
],
"total": 5000,
"trackId": "kolSearch_00fbc9950e0d451ba597c36cafd6b555",
"highlightWords": [],
"resultType": 1,
"redirect2NickSearch": false
}
}💡 Note: For list data, the example shows only 1-2 items for simplicity. The actual count depends on the API response.