Quick search

Table Of Contents


New in version 1.0.8.

You can use the UrlRequest to make asynchronous requests on the web and get the result when the request is completed. The spirit is the same as the XHR object in Javascript.

The content is also decoded if the Content-Type is application/json and the result automatically passed through json.loads.

The syntax to create a request:

from kivy.network.urlrequest import UrlRequest
req = UrlRequest(url, on_success, on_redirect, on_failure, on_error,
                 on_progress, req_body, req_headers, chunk_size,
                 timeout, method, decode, debug, file_path, ca_file,

Only the first argument is mandatory: the rest are optional. By default, a “GET” request will be sent. If the UrlRequest.req_body is not None, a “POST” request will be sent. It’s up to you to adjust UrlRequest.req_headers to suit your requirements and the response to the request will be accessible as the parameter called “result” on the callback function of the on_success event.

Example of fetching weather in Paris:

def got_weather(req, results):
    for key, value in results['weather'][0].items():
        print(key, ': ', value)

req = UrlRequest(

Example of Posting data (adapted from httplib example):

import urllib

def bug_posted(req, result):
    print('Our bug is posted !')

params = urllib.urlencode({'@number': 12524, '@type': 'issue',
    '@action': 'show'})
headers = {'Content-type': 'application/x-www-form-urlencoded',
          'Accept': 'text/plain'}
req = UrlRequest('bugs.python.org', on_success=bug_posted, req_body=params,

If you want a synchronous request, you can call the wait() method.

class kivy.network.urlrequest.UrlRequest(url, on_success=None, on_redirect=None, on_failure=None, on_error=None, on_progress=None, req_body=None, req_headers=None, chunk_size=8192, timeout=None, method=None, decode=True, debug=False, file_path=None, ca_file=None, verify=True, proxy_host=None, proxy_port=None, proxy_headers=None)[source]

Bases: threading.Thread

A UrlRequest. See module documentation for usage.

Changed in version 1.5.1: Add debug parameter

Changed in version 1.0.10: Add method parameter

Changed in version 1.8.0: Parameter decode added. Parameter file_path added. Parameter on_redirect added. Parameter on_failure added.

Changed in version 1.9.1: Parameter ca_file added. Parameter verify added.

Changed in version 1.10.0: Parameters proxy_host, proxy_port and proxy_headers added.

url: str

Complete url string to call.

on_success: callback(request, result)

Callback function to call when the result has been fetched.

on_redirect: callback(request, result)

Callback function to call if the server returns a Redirect.

on_failure: callback(request, result)

Callback function to call if the server returns a Client or Server Error.

on_error: callback(request, error)

Callback function to call if an error occurs.

on_progress: callback(request, current_size, total_size)

Callback function that will be called to report progression of the download. total_size might be -1 if no Content-Length has been reported in the http response. This callback will be called after each chunk_size is read.

req_body: str, defaults to None

Data to sent in the request. If it’s not None, a POST will be done instead of a GET.

req_headers: dict, defaults to None

Custom headers to add to the request.

chunk_size: int, defaults to 8192

Size of each chunk to read, used only when on_progress callback has been set. If you decrease it too much, a lot of on_progress callbacks will be fired and will slow down your download. If you want to have the maximum download speed, increase the chunk_size or don’t use on_progress.

timeout: int, defaults to None

If set, blocking operations will timeout after this many seconds.

method: str, defaults to ‘GET’ (or ‘POST’ if body is specified)

The HTTP method to use.

decode: bool, defaults to True

If False, skip decoding of the response.

debug: bool, defaults to False

If True, it will use the Logger.debug to print information about url access/progression/errors.

file_path: str, defaults to None

If set, the result of the UrlRequest will be written to this path instead of in memory.

ca_file: str, defaults to None

Indicates a SSL CA certificate file path to validate HTTPS certificates against

verify: bool, defaults to True

If False, disables SSL CA certificate verification

proxy_host: str, defaults to None

If set, the proxy host to use for this connection.

proxy_port: int, defaults to None

If set, and proxy_host is also set, the port to use for connecting to the proxy server.

proxy_headers: dict, defaults to None

If set, and proxy_host is also set, the headers to send to the proxy server in the CONNECT request.


Return the size of a chunk, used only in “progress” mode (when on_progress callback is set.)

decode_result(result, resp)[source]

Decode the result fetched from url according to his Content-Type. Currently supports only application/json.


Return the error of the request. This value is not determined until the request is completed.


Return the Connection class for a particular scheme. This is an internal function that can be expanded to support custom schemes.

Actual supported schemes: http, https.


Return True if the request has finished, whether it’s a success or a failure.

req_body = None

Request body passed in __init__

req_headers = None

Request headers passed in __init__


If the request has been completed, return a dictionary containing the headers of the response. Otherwise, it will return None.


Return the status code of the response if the request is complete, otherwise return None.


Return the result of the request. This value is not determined until the request is finished.

url = None

Url of the request


Wait for the request to finish (until resp_status is not None)


This method is intended to be used in the main thread, and the callback will be dispatched from the same thread from which you’re calling.

New in version 1.1.0.