API概览
## 1 接口简介
青果代理IP提供了功能丰富的API接口，满足开发者在各种场景下的调用需求。
所有接口支持 HTTP 或者 HTTPS 请求，部分接口采用 GET 方法，部分接口采用 POST 方法；接口返回数据的格式支持文本、json、xml。
具体请参见接口文档。
## 2 API列表
- [短效代理](https://www.qg.net/doc/2254.html)
- [独享代理](https://www.qg.net/doc/2141.html)
- [长效代理](https://www.qg.net/doc/2143.html)
- [短效代理（全球HTTP）](https://www.qg.net/doc/2144.html)
- [隧道代理相关](https://www.qg.net/doc/1940.html)
## 3 测试代理可用性
### 3.1 生成API链接
对于代理提取API，您可以到提取工具在线生成API链接，内置到您的程序中：
[提取代理API链接生成 ＞](https://www.qg.net/tools/IPget.html "提取代理API链接生成 ＞＞")
其他接口请查看API文档，获取接口url和参数说明，自己生成API链接。
### 3.2 测试API链接
**浏览器测试**
您可以把生成的API链接直接在浏览器里打开，查看返回结果。例如，您直接点击如下api链接
https://proxy.qg.net/query?Key=0B***607
**命令行测试**
如果您在linux系统下，可以通过curl命令请求API链接查看结果：
`curl "https://proxy.qg.net/allocate?Key=请改成您的Key"`
## 4 接口返回错误码
公共接口返回错误码
| 错误码 | 描述 |
| ------ | ------------------------- |
| -1 | 未知错误 |
| -10 | 参数不合法 |
| -11 | 请求过于频繁 |
| -12 | Authkey被封禁 |
| -13 | 当前客户端IP不在授权名单中 |
| -14 | Pwd不合法 |
| -15 | Authkey对应的业务无此权限 |
| -100 | 计划不存在或已过期 |
| -103 | 资源不足 |
| -104 | 申请资源失败 |
| -105 | 释放的IP数超过允许释放的IP数 |
## 5 代码样例
查看API调用的[代码样例 ＞](https://www.qg.net/doc/172.html)
数据结构
## Response
请求响应详情
被所有接口引用。
| 名称 | 类型 | 描述 |
| ---------- | ------ | ------------------------------------------------------------ |
| code | String | 响应[状态码](https://www.qg.net/doc/1838.html)。 |
| data | Any | 请求响应数据。 |
| message | String | 报错信息。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## IP
代理IP详情
被如下接口引用：[短效代理提取](https://www.qg.net/doc/1846.html), [短效代理查询](https://www.qg.net/doc/1847.html), [短效代理资源池](https://www.qg.net/doc/1850.html), [独享代理提取](https://www.qg.net/doc/1840.html), [独享代理查询](https://www.qg.net/doc/1841.html), [独享代理更换](https://www.qg.net/doc/1843.html), [长效代理提取](https://www.qg.net/doc/1863.html), [长效代理查询](https://www.qg.net/doc/1861.html)。
| 名称 | 类型 | 描述 |
| -------- | ------ | ------------------------------------------------------------ |
| proxy_ip | String | 代理真实出口IP地址，比如: 120.11.67.89。 |
| server | String | 代理服务地址，挂代理直接使用这个字段信息，比如：120.11.67.89:8090。 |
| area | String | 代理IP地区信息。 |
| isp | String | 代理IP运营商信息。 |
| deadline | String | 动态代理表示代理IP的存活截至时间；
长效代理表示代理IP的可释放时间。 |
## Task
单次提取详情
被如下接口引用：[短效代理提取](https://www.qg.net/doc/1846.html), [短效代理查询](https://www.qg.net/doc/1847.html), [短效代理资源池](https://www.qg.net/doc/1850.html), [独享代理提取](https://www.qg.net/doc/1840.html), [独享代理查询](https://www.qg.net/doc/1841.html), [独享代理更换](https://www.qg.net/doc/1843.html), [长效代理提取](https://www.qg.net/doc/1863.html), [长效代理查询](https://www.qg.net/doc/1861.html)。
| 名称 | 类型 | 描述 |
| ------- | --------------- | ---------------- |
| task_id | String | 本次提取的标识。 |
| ips | Array of [IP]() | IP资源信息。 |
| num | Integer | IP资源总数。 |
## Balance
余额详情
被如下接口引用：[短效代理余额查询](https://www.qg.net/doc/2256.html)。
| 名称 | 类型 | 描述 |
| ------- | ------- | -------------- |
| balance | Integer | 剩余资源总数。 |
## Channel
通道数详情
被如下接口引用：[短效代理通道数查询](https://www.qg.net/doc/1849.html), [独享代理通道数查询](https://www.qg.net/doc/1844.html), [长效代理通道数查询](https://www.qg.net/doc/1860.html)。
| 名称 | 类型 | 描述 |
| ----- | ------- | ------------ |
| total | Integer | 总通道数。 |
| idle | Integer | 空闲通道数。 |
## ResourceAreaISP
资源可用地区和运营商详情
被如下接口引用：[短效代理资源地区查询](https://www.qg.net/doc/2257.html), [独享代理资源地区查询](https://www.qg.net/doc/1845.html), [长效代理资源地区查询](https://www.qg.net/doc/1859.html)。
| 名称 | 类型 | 描述 |
| --------- | ------- | ---------------- |
| area | String | 地区信息。 |
| area_code | Integer | 地区码。 |
| isp | String | 运营商信息。 |
| isp_code | Integer | 运营商编码。 |
| available | Bool | 是否有可用资源。 |
## Monopoly
独占资源详情
被如下接口引用：[独享代理提取](https://www.qg.net/doc/1840.html), [独享代理查询](https://www.qg.net/doc/1841.html)。
| 名称 | 类型 | 描述 |
| --------------- | ------ | ------------------------------------ |
| uuid | String | 资源唯一标识。 |
| area | String | 地区信息。 |
| isp | String | 运营商信息。 |
| state | String | 资源状态。 |
| ip | String | 最新IP，仅当state="在线"有值。 |
| heartbeat | String | 最后一次心跳，仅当state="在线"有值。 |
| monopolize_time | String | 独占的时间。 |
| last_dial_time | String | 最后一次切换的时间。 |
## ResourceAreaISPWithIdle
地区和运营商可用独占资源统计
被如下接口引用：[独享代理资源地区查询](https://www.qg.net/doc/1845.html)。
| 名称 | 类型 | 描述 |
| --------- | ------- | ------------ |
| area | String | 地区信息。 |
| area_code | Integer | 地区码。 |
| isp | String | 运营商信息。 |
| isp_code | Integer | 运营商编码。 |
| idle | Integer | 空闲资源数。 |
长效代理-查询资源地区
## 1. 接口描述
接口请求域名： static.proxy.qg.net。
本接口 (/resources) 用于长效代理产品查询资源地区的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [ResourceAreaISP](https://www.qg.net/doc/1839.html) | 资源地区列表。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://static.proxy.qg.net/resources?key=<您的key信息>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [
{
"area": "福建省泉州市",
"area_code": 350500,
"isp": "电信",
"isp_code": 1,
"available": false
},
{
"area": "河南省商丘市",
"area_code": 411400,
"isp": "电信",
"isp_code": 1,
"available": true
}
],
"request_id": "51024a8b-a8a5-4e78-9301-cb500a8c083e"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
长效代理-查询通道数接口
## 1. 接口描述
接口请求域名： static.proxy.qg.net。
本接口 (/channels) 用于长效代理产品通道数查询的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data.toal | Integer | key的通道总数。 |
| data.idle | Integer | 空闲通道数。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://static.proxy.qg.net/channels?key=<您的key信息>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": {
"total": 10,
"idle": 5
},
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
长效代理-释放IP资源接口
## 1. 接口描述
接口请求域名： static.proxy.qg.net。
本接口 (/delete) 是用于长效代理-静态型产品释放IP资源的接口。（动态型无此功能）
默认接口请求频率限制：每通道一周有两次释放机会。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| task | 否 | String | 按提取批次释放。支持批量释放，用逗号隔开。比如：Z5p2DKKCSyhocKEa,xsQGWfoaX99WcYnU。 |
| ip | 否 | String | 按IP释放。支持批量释放，用逗号隔开。比如：129.123.7.89,23.11.112.51。 |
注意：task和ip必选其一。如果需要释放全部IP，用task='*'即可。
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------ | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://static.proxy.qg.net/delete?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ------------------------ | -------------------------------------------------------- |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| DELETE_LIMIT_EXCEEDED | 释放频率超出限制。 |
| STATIC_DELETE_TIME_LIMIT | 静态资源需要24小时后才能释放。 |
长效代理-查询在用IP资源接口
## 1. 接口描述
接口请求域名： static.proxy.qg.net。
本接口 (/query) 用于长效代理产品查询在用的IP资源的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| task | 否 | String | 提取批次筛选。支持多批次筛选，用逗号隔开。比如："Z5p2DKKCSyhocKEa,kAEaWHucf8iPXm0O"。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------------------------------------------------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data.tasks | Array of [Task](https://www.qg.net/doc/1839.html) | 提取批次列表。
**注：Task结构中的IP结构中的server才是代理地址，proxy_ip是代理的真实出口IP。** |
| data.num | Integer | 提取批次数量。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://static.proxy.qg.net/query?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": {
"tasks": {
"task_id": "Z5p2DKKCSyhocKEa",
"ips": [
{
"proxy_ip": "123.54.55.24",
"server": "123.54.55.24:59419",
"area": "河南省商丘市",
"isp": "电信",
"deadline": "2023-02-25 15:38:36"
}
],
"num": 1
},
"num": 1
},
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
长效代理-提取IP接口
## 1. 接口描述
接口请求域名： static.proxy.qg.net。
本接口 (/get) 用于长效代理产品提取IP资源的接口。
默认接口请求频率限制：（通道数*5+10）次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------- | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| area | 否 | String | 按地区提取。 |
| isp | 否 | Integer | 按运营商提取。
0: 不筛选
1: 电信
2: 移动
3: 联通 |
| num | 否 | Integer | 提取个数，默认为1。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ------------ | ----------------------------------------------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data.task_id | String | 提取批次的ID。 |
| data.ips | Array of [IP](https://www.qg.net/doc/1839.html) | IP资源列表。
**注：IP结构中的server才是代理地址，proxy_ip是代理的真实出口IP。** |
| data.num | Integer | 提取到的IP资源数量。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://static.proxy.qg.net/get?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": {
"task_id": "0LIKQ3S1_task",
"ips": [
{
"proxy_ip": "123.54.55.24",
"server": "123.54.55.24:59419",
"area": "河南省商丘市",
"isp": "电信",
"deadline": "2023-02-25 15:38:36"
}
],
"num": 1
},
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| NO_RESOURCE_FOUND | 资源不足。 |
| FAILED_OPERATION | 提取失败。 |
长效代理-API接口介绍
## 1说明
通过编码使用长效代理主要有以下4步骤：
1.先在[提取工具](https://www.qg.net/tools/IPget.html)或[调试工具](https://www.qg.net/tools/IPdebug.html)上获取api接口；
2.使用白名单或账密进行授权验证；
3.进行代理测试；[查看测试步骤＞＞](https://www.qg.net/doc/1574.html "查看测试步骤")
4.参考[代码样例](https://www.qg.net/list/192.html)编写采集程序，使用代理IP。
## 2 API接口
长效代理API接口一览
| 接口类型 | API | 描述 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 资源相关 | - [get](https://www.qg.net/doc/product/6_258_274/1863.html)
- [delete](https://www.qg.net/doc/product/6_258_274/1862.html)
- [query](https://www.qg.net/doc/product/6_258_274/1861.html)
- [channels](https://www.qg.net/doc/product/6_258_274/1860.html)
- [resources](https://www.qg.net/doc/product/6_258_274/1859.html)
| - 提取IP资源
- 释放IP资源
- 查询在用IP资源
- 查询通道数
- 查询资源地区
|
| 白名单相关 | -[whitelist/query](https://www.qg.net/doc/180.html "whitelist/query")
- [whitelist/add](https://www.qg.net/doc/178.html "whitelist/add")
- [whitelist/del](https://www.qg.net/doc/179.html "删除白名单")
| - 查询IP的白名单
- 添加IP的白名单
- 删除IP的白名单 |
短效代理-合并业务-提取IP接口
## 1. 接口描述
接口请求域名： share.proxy.qg.net。
本接口 (/aggregate/get) 用于短效代理产品弹性提取模式下提取IP的接口。
默认接口请求频率限制：60次/分钟。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------- | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| area | 否 | String | 按地区提取。支持多地区筛选，逗号隔开。比如："350500,330700"。 |
| area_ex | 否 | String | 排除某些地区提取。支持多地区排除，用逗号隔开。比如："440100,450000"。 |
| isp | 否 | Integer | 按运营商提取。
0: 不筛选
1: 电信
2: 移动
3: 联通 |
| num | 否 | Integer | 提取个数，默认为1 |
| distinct | 否 | Bool | 去重提取，默认为false。如果为true则不会提取到已经在使用的IP资源。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | --------------------------------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [IP](https://www.qg.net/doc/1839.html) | IP资源列表。
**注：IP结构中的server才是代理地址，proxy_ip是代理的真实出口IP。** |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://share.proxy.qg.net/aggregate/get?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [
{
"proxy_ip": "123.54.55.24",
"server": "123.54.55.24:59419",
"area": "河南省商丘市",
"isp": "电信",
"deadline": "2023-02-25 15:38:36"
}
],
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | -------------------------------------------------------- |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| NO_RESOURCE_FOUND | 资源不足。 |
| FAILED_OPERATION | 提取失败。 |
| EXTRACT_LIMIT_EXCEEDED | 超出提取配额。今天提取的IP数超出了购买的IP数，请明天再提取使用或者升级IP数。 |
短效代理-合并业务-API接口介绍
## 1 说明
通过编码使用短效代理-合并业务主要有以下4步骤：
1.通过文档下放的API接口信息自行设置接口地址等；
2.使用白名单或账密进行授权验证；
3.进行代理测试；[查看测试步骤＞＞](https://www.qg.net/doc/1574.html "查看测试步骤")
4.参考[代码样例](https://www.qg.net/list/192.html)编写采集程序，使用代理IP。
## 2 API接口
短效代理-弹性提取API接口一览
| 接口类型 | API | 描述 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 资源相关 | - [aggregate/get](https://www.qg.net/doc/product/6_255_263_264/2255.html) | - 提取IP资源 |
| 白名单相关 | - [whitelist/query](https://www.qg.net/doc/180.html "whitelist/query")
- [whitelist/add](https://www.qg.net/doc/178.html "whitelist/add")
- [whitelist/del](https://www.qg.net/doc/179.html "删除白名单")
| - 查询IP的白名单
- 添加IP的白名单
- 删除IP的白名单 |
**提示：**短效代理-合并业务为了区分当前使用的是业务key还是合并业务的key，接口地址与其他四种提取方式做了区分。
请点击文字查看其他产品接口：
[通道提取 > ](https://www.qg.net/doc/product/6_255_263_267/2139.html)
[均匀提取 ＞](https://www.qg.net/doc/product/6_255_263_266/2258.html)
[通道提取 ＞](https://www.qg.net/doc/product/6_255_263_267/2139.html)
[按量提取 ＞](https://www.qg.net/doc/product/6_255_263_265/2140.html)
