> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-scraper-api/integration-methods/realtime.md).

# Realtime

Oxylabs 网页爬虫API 的 Realtime 集成。使用 JSON 格式载荷，在提交任务后保持 HTTPS 连接打开，直到返回结果或错误。

Realtime 是一种同步集成方法。它 **需要保持连接打开** 直到作业成功完成或返回错误。它是实现最快的方法；对于大量数据，请使用 [**Push-Pull**](/products/cn/web-scraper-api/integration-methods/push-pull.md) 替代。

## 作业提交

### 端点

用于作业提交的 Realtime API 端点是：

```
POST https://realtime.oxylabs.io/v1/queries
```

### 输入

请在 JSON 载荷中提供作业参数，如下方示例所示。Python 和 PHP 示例包含注释以便说明。

{% tabs %}
{% tab title="cURL" %}

```shell
curl --user \"USERNAME:PASSWORD\" \\
'https://realtime.oxylabs.io/v1/queries' \\
-H \"Content-Type: application/json\" \\
-d '{"source": "universal", "url": "https://example.com", "geo_location": "United States"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
from pprint import pprint


# Structure payload.
payload = {
    "source": "universal", # Source you choose e.g. "universal"
    "url": "https://example.com", # Check the docs of the specific source you're using to see if you should use "url" or "query"
    "geo_location": "United States", # Some sources accept post codes and/or coordinates
    #"render" : "html", # Uncomment if you want to render JavaScript on the page
    #"render" : "png", # Uncomment if you want to take a screenshot of a scraped web page
    #"parse" : True, # Check what sources support parsed data
}

# Get response.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('YOUR_USERNAME', 'YOUR_PASSWORD'), #Your credentials go here
    json=payload,
)

不再返回带有作业状态和结果 url 的响应，而是返回
包含结果的 JSON 响应。
pprint(response.json())
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$params = array(
    'source' => 'universal', //Source you choose e.g. "universal"
    'url' => 'https://example.com', // Check the docs of the specific source you're using to see if you should use "url" or "query"
    'geo_location' => 'United States', //Some sources accept zip-code or coordinates
    //'render' => 'html', // Uncomment if you want to render JavaScript within the page
    //'render' => 'png', // Uncomment if you want to take a screenshot of a scraped web page
    //'parse' => TRUE, // Check what sources support parsed data
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "YOUR_USERNAME" . ":" . "YOUR_PASSWORD"); //Your credentials go here

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";

            var parameters = new Dictionary<string, string>()
            {
                { "source", "universal" },
                { "url", "https://example.com" },
                { "geo_location", "United States" },
            };


            var client = new HttpClient();

            Uri baseUri = new Uri("https://realtime.oxylabs.io");
            client.BaseAddress = baseUri;

            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
            requestMessage.Content = JsonContent.Create(parameters);

            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);

            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();

            Console.WriteLine(contents);
        }
    }
}
```

{% endtab %}

{% tab title="Golang" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	payload := map[string]string{
		"source": "universal",
		"url": "https://example.com",
		"geo_location": "United States",
	}

	jsonValue, _ := json.Marshal(payload)

	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://realtime.oxylabs.io/v1/queries",
		bytes.NewBuffer(jsonValue),
	)

	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)

	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

```

{% endtab %}

{% tab title="Java" %}

```java
package org.example;

import okhttp3.*;
import org.json.JSONObject;

public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";

    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "universal");
        jsonObject.put("url", "https://example.com");
        jsonObject.put("geo_location", "United States");

        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);

            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };

        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();

        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://realtime.oxylabs.io/v1/queries")
                .post(body)
                .build();

        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }

        System.exit(0);
    }

    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

```

{% endtab %}

{% tab title="Node.js" %}

```javascript
import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
  source: 'universal',
  url: 'https://example.com',
  geo_location: 'United States'
};
const response = await fetch('https://realtime.oxylabs.io/v1/queries', {
  method: 'post',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  }
});

console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### 输出

Realtime API 在输出中支持以下结果类型：

* **HTML**：从目标网页抓取的原始 HTML 内容；
* **JSON**：从 HTML 内容解析出的结构化数据，以 JSON 格式呈现；
* **PNG**：以 PNG 格式编码的已渲染页面 Base64 截图。
* **XHR：** [XHR 请求](/products/cn/web-scraper-api/features/result-processing-and-storage/output-types/capturing-network-requests-fetch-xhr.md) 在加载页面时发出的。
* **Markdown：** [Markdown](/products/cn/web-scraper-api/features/result-processing-and-storage/output-types/markdown-output.md) 网页的。

此表说明了根据 API 请求载荷中包含的参数，默认结果类型：

| 渲染参数   | 解析参数   | 默认输出 |
| ------ | ------ | ---- |
| -      | -      | html |
| `html` | -      | html |
| `png`  | -      | png  |
| -      | `true` | json |
| `html` | `true` | json |
| `png`  | `true` | png  |

默认情况下，Realtime 仅返回 **默认输出** 作为你的载荷。若要改为接收一个或多个可用输出，请添加 `type` 查询参数添加到端点中，如下所示。每个请求的 type 都会作为单独条目返回到 `results` 数组。这就是 [**多结果类型**](/products/cn/web-scraper-api/features/result-processing-and-storage/output-types/multi-format-output.md) 功能，并且在 Realtime 和 [**Push-Pull**](/products/cn/web-scraper-api/integration-methods/push-pull.md).

```
POST https://realtime.oxylabs.io/v1/queries?type=raw,parsed,png
```

{% hint style="info" %}
某些来源有一个 [专用解析器](/products/cn/web-scraper-api/features/result-processing-and-storage/dedicated-parsers.md)；请使用 `parse: true` 用于这些来源。对于任何其他目标，请使用 [自定义解析器。](/products/cn/web-scraper-api/features/custom-parser.md) 每个已解析结果都带有一个 `parse_status_code`；请参见 [响应代码](/products/cn/web-scraper-api/response-codes.md#parsers) 以了解各值的含义。
{% endhint %}

#### 输出示例：

```json
{
  "results": [
    {
      "content": "<!doctype html><html lang=\"en\"><head><title>Example Domain</title></head><body>CONTENT</body></html>",
      "created_at": "2026-08-21 13:00:20",
      "updated_at": "2026-08-21 13:00:21",
      "page": 1,
      "url": "https://example.com",
      "job_id": "7496551765458818050",
      "is_render_forced": false,
      "type": "raw",
      "status_code": 200
    }
  ]
}
```

{% hint style="info" %}
响应还包含 `_request`, `_response`，以及 `session_info` 对象，出于简洁起见此处省略。使用 `parse` 时， `parser_type` 和 `parser_preset` 也会一并返回。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/cn/web-scraper-api/integration-methods/realtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.