报表

获取流量使用报表

GET /residential/data-usage-report

以CSV文件形式返回指定住宅代理用户或子用户的流量使用报表。hash 必须属于当前已认证账号。若日期范围为空，则返回仅包含表头的CSV文件。

Query Parameters

名称	类型	说明
hash	字符串	要生成报表的住宅代理用户或子用户的 app_hash
date_from	字符串	报表范围的开始日期，格式为 Y-m-d
date_to	字符串	报表范围的结束日期，格式为 Y-m-d。必须等于或晚于 date_from
measurement_unit	字符串	流量数值的单位，可选值：B、KB、MB、GB
rounding_decimal	整数	流量数值的小数位数（必须为 0 或更大）
time_zone	字符串	可选。 用于按日期归集流量的 IANA 时区名称（例如 Europe/London、America/New_York、UTC）。不区分大小写。若不提供，则使用默认时区。

除 time_zone 外，所有参数均为必填项。

请求示例：

cURL

curl -X GET "https://resi-api.iproyal.com/v1/residential/data-usage-report?hash=asd48w4f5c1s2a5w4f8h5t6r1v&date_from=2026-01-01&date_to=2026-01-31&measurement_unit=GB&rounding_decimal=2" \
    -H "Authorization: Bearer <your_api_token>" \
    -o data-usage-report.csv

PHP

<?php
$query = http_build_query([
    'hash' => 'asd48w4f5c1s2a5w4f8h5t6r1v',
    'date_from' => '2026-01-01',
    'date_to' => '2026-01-31',
    'measurement_unit' => 'GB',
    'rounding_decimal' => 2,
]);

$ch = curl_init("https://resi-api.iproyal.com/v1/residential/data-usage-report?{$query}");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <your_api_token>']);
curl_setopt($ch, CURLOPT_FILE, fopen('data-usage-report.csv', 'w'));
curl_exec($ch);
curl_close($ch);

Python

import requests

params = {
    "hash": "asd48w4f5c1s2a5w4f8h5t6r1v",
    "date_from": "2026-01-01",
    "date_to": "2026-01-31",
    "measurement_unit": "GB",
    "rounding_decimal": 2,
}
headers = {"Authorization": "Bearer <your_api_token>"}

response = requests.get(
    "https://resi-api.iproyal.com/v1/residential/data-usage-report",
    params=params,
    headers=headers,
    stream=True,
)

with open("data-usage-report.csv", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

Node.js

const fs = require("fs");
const https = require("https");

const params = new URLSearchParams({
    hash: "asd48w4f5c1s2a5w4f8h5t6r1v",
    date_from: "2026-01-01",
    date_to: "2026-01-31",
    measurement_unit: "GB",
    rounding_decimal: "2",
});

const options = {
    headers: { Authorization: "Bearer <your_api_token>" },
};

https.get(
    `https://resi-api.iproyal.com/v1/residential/data-usage-report?${params}`,
    options,
    (res) => res.pipe(fs.createWriteStream("data-usage-report.csv")),
);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://resi-api.iproyal.com/v1/residential/data-usage-report"
        + "?hash=asd48w4f5c1s2a5w4f8h5t6r1v"
        + "&date_from=2026-01-01"
        + "&date_to=2026-01-31"
        + "&measurement_unit=GB"
        + "&rounding_decimal=2"))
    .header("Authorization", "Bearer <your_api_token>")
    .GET()
    .build();

client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("data-usage-report.csv")));

Go

package main

import (
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://resi-api.iproyal.com/v1/residential/data-usage-report" +
        "?hash=asd48w4f5c1s2a5w4f8h5t6r1v" +
        "&date_from=2026-01-01&date_to=2026-01-31" +
        "&measurement_unit=GB&rounding_decimal=2"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer <your_api_token>")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    out, _ := os.Create("data-usage-report.csv")
    defer out.Close()
    io.Copy(out, resp.Body)
}

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer <your_api_token>");

var url = "https://resi-api.iproyal.com/v1/residential/data-usage-report"
    + "?hash=asd48w4f5c1s2a5w4f8h5t6r1v"
    + "&date_from=2026-01-01&date_to=2026-01-31"
    + "&measurement_unit=GB&rounding_decimal=2";

await using var stream = await client.GetStreamAsync(url);
await using var file = File.Create("data-usage-report.csv");
await stream.CopyToAsync(file);

响应

该接口以附件形式返回CSV文件。

请求头：

Content-Type: text/csv
Content-Disposition: attachment; filename="data-usage-{hash}-{date_from}-{date_to}.csv"

响应示例：

date,hostname,port,data,measurement unit,requests count
2026-01-01,example.com,443,2.15,GB,1248
2026-01-01,api.example.com,443,4.78,GB,5310
2026-01-01,cdn.example.com,80,0.92,GB,612
2026-01-02,example.com,443,1.84,GB,1102
2026-01-02,api.example.com,443,5.23,GB,6047
2026-01-03,example.com,443,3.07,GB,2415
2026-01-03,images.example.com,443,8.41,GB,9823
,,total:,26.40,,26557