Realtime

Integración Realtime para la Web Scraper API de Oxylabs. Mantén la conexión HTTPS abierta desde el envío del trabajo hasta que se devuelvan los resultados o un error, usando cargas útiles formateadas en JSON.

Realtime es un método de integración sincrónica. Requiere mantener la conexión abierta hasta que el trabajo se complete correctamente o devuelva un error. Es el método más rápido de implementar; para grandes volúmenes de datos, usa Push-Pull en su lugar.

Envío de trabajos

Endpoint

El endpoint de la Realtime API para el envío de trabajos es:

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

Entrada

Proporciona los parámetros del trabajo en una carga útil JSON como se muestra en los ejemplos de abajo. Los ejemplos de Python y PHP incluyen comentarios para mayor claridad.

cURL

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"}'

Python

import requests
from pprint import pprint


# Estructura la carga útil.
payload = {
    "source": "universal", # Fuente que elijas, por ejemplo, "universal"
    "url": "https://example.com", # Consulta la documentación de la fuente específica que estás usando para ver si debes usar "url" o "query"
    "geo_location": "United States", # Algunas fuentes aceptan códigos postales y/o coordenadas
    #"render" : "html", # Descomenta si quieres renderizar JavaScript en la página
    #"render" : "png", # Descomenta si quieres tomar una captura de pantalla de una página web raspada
    #"parse" : True, # Comprueba qué fuentes admiten datos analizados
}

# Obtén la respuesta.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('YOUR_USERNAME', 'YOUR_PASSWORD'), #Tus credenciales van aquí
    json=payload,
)

# En lugar de una respuesta con el estado del trabajo y la URL de resultados, esto devolverá la
# respuesta JSON con los resultados.
pprint(response.json())

PHP

<?php

$params = array(
    'source' => 'universal', //Fuente que elijas, por ejemplo, "universal"
    'url' => 'https://example.com', // Consulta la documentación de la fuente específica que estás usando para ver si debes usar "url" o "query"
    'geo_location' => 'United States', //Algunas fuentes aceptan códigos postales o coordenadas
    //'render' => 'html', // Descomenta si quieres renderizar JavaScript dentro de la página
    //'render' => 'png', // Descomenta si quieres tomar una captura de pantalla de una página web raspada
    //'parse' => TRUE, // Comprueba qué fuentes admiten datos analizados
);

$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"); //Tus credenciales van aquí

$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);

C#

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);
        }
    }
}

Golang

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))
}

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();
    }
}

Node.js

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());

Salida

Realtime API admite estos tipos de resultado en la salida:

• HTML: El contenido HTML en bruto extraído de la página web de destino;
• JSON: Datos estructurados analizados a partir del contenido HTML, formateados en JSON;
• PNG: Captura de pantalla codificada en Base64 de la página renderizada en formato PNG.
• XHR: Solicitudes XHR realizadas mientras se cargaba la página.
• Markdown: Markdown de una página web.

Esta tabla explica los tipos de resultado predeterminados según los parámetros incluidos en la carga útil de la solicitud de la API:

Parámetro de renderizado	Parámetro de parseo	Salida predeterminada
-	-	html
html	-	html
png	-	png
-	true	json
html	true	json
png	true	png

De forma predeterminada, Realtime solo devuelve la salida predeterminada para tu carga útil. Para recibir una o más de las salidas disponibles en su lugar, añade el tipo parámetro de consulta al endpoint, como se muestra abajo. Cada tipo solicitado se devuelve como una entrada separada en el results Esta es la funcionalidad de varios tipos de resultado y funciona igual en Realtime y Push-Pull.

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

Algunas fuentes tienen un parser dedicado; usa parse: true con esas. Para cualquier otro destino, usa Custom Parser. Cada resultado analizado lleva un parse_status_code; consulta los códigos de respuesta para ver qué significa cada valor.

Ejemplo de salida:

{
  "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
    }
  ]
}

La respuesta también incluye _request, _response, y session_info objetos, omitidos aquí por brevedad. Cuando parse se usa, parser_type y parser_preset también se devuelven.