WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

URLRead

✖
URLRead[url]

sends a request to a URL and reads back the response, returning it as a response object.

✖
URLRead[assoc]

sends a request to a URL built from an association of components and metadata elements.

✖

sends a request specified by a symbolic HTTPRequest object.

✖
URLRead[req,"elem"]

returns only the element elem from the response.

✖
URLRead[req,{"elem1","elem2",…}]

returns an association of the values of the elements elemi.

✖
URLRead[{req1,req2,…},…]

sends the requests reqi in parallel, giving a list of the results obtained.

Details and Options

  • In URLRead[url], url can be a string, a URL object, or a cloud object.
  • The URL can also be specified by giving the following components in an association:
  • "Scheme"URL scheme
    "User"user information
    "Domain"domain name or host
    "Port"port number (as an integer)
    "Path"path list or string
    "Query"query string or list of parameter-value pairs
  • The following additional entries can also be included in the association, as in HTTPRequest:
  • Method"GET"method to use for the HTTP request
    "Body"""contents of message body to be sent
    "ContentType"Automaticcontent-type header for the request
    "Username"""username to use for the request
    "Password"""password to use for the request
    "Cookies"Automaticcookies to send to the server
    "UserAgent"Automaticuser agent string to send
    "Headers"{}list of headers to be sent to the server
  • The setting for "Body" can have the following forms:
  • "string"string to be sent literally
    ByteArray[…]byte array to be sent literally
    {b1,b2,b3,…}list of bytes to be sent literally
    {"par1""val1","par2""val2",…}list of parameters and values to be sent URL encoded
    {"par1"{"val11",…},…}list with multiple values associated with a single parameter
    <|"key1"val1,"key2"val2,…|>alternative form for list of parameters and values
    {"par1"File[…],"par2"File[…],…}files to be sent with multipart encoding
    {"par1"assoc1,…}multipart encoding with detailed specifications for each part
  • Detailed specifications for each part in a multipart encoding are given as an association with the following elements:
  • "Content"the content, as a string, byte array, file object, etc.
    "Name"the name to assign to the part
    "MIMEType"the MIME type to assign to the part
  • The setting "Cookies"->Automatic specifies that cookies from $Cookies for the domain corresponding to url should be sent. "Cookies" can also give an explicit list of associations representing cookies. "Cookies"->None specifies that no cookies should be sent.
  • The default "UserAgent" is typically "Wolfram HTTPClient xxxx", where xxxx is a version number.
  • The setting for "Headers" can be a list of rules or an association.
  • In URLRead[req,elem], the following elements can be used:
  • "Body"body of the response as a string
    "BodyByteArray"raw body of the response as a byte array
    "BodyBytes"raw body of the response as a list of byte values
    "Headers"list of headers received in the response
    "Cookies"list of cookies received in the response
    "ContentType"content type header
    "StatusCode"status code returned by the server
    "StatusCodeDescription"plain text description of status code
    "Stream"stream object to read the response body
    {elem1,elem2,…}an association of the elements elemi
    Automaticsymbolic HTTPResponse object
    Allan association of all elements
  • URLRead supports the following options:
  • AuthenticationAutomaticauthentication information to send
    CharacterEncodingAutomaticcharacter encoding for strings received
    ConnectionSettingsAutomaticspeed and other settings for the connection
    CookieFunction Automaticfunction to apply to each cookie received
    FollowRedirects Truewhether to follow HTTP redirects
    InteractiveTruewhether to allow interactive authentication dialogs
    TimeConstraint Infinitytime to wait for a response
    VerifySecurityCertificates Truewhether to verify SSL security certificates
  • The setting CharacterEncoding->"enc" specifies that all strings that appear in the request should be encoded using the encoding enc before being sent to the server.
  • The setting CharacterEncoding->None specifies that no change should be made to strings before sending them to the server.
  • With CharacterEncoding->Automatic, the encoding is taken from the "ContentType" element if this is specified; otherwise, the encoding is "UTF8".
  • TimeConstraint->t allows a maximum of t seconds for connection to the URL and reading from it.
  • TimeConstraint-><|"Connecting"->tc,"Reading"->tr|> specifies separate timeouts for connecting to the URL and reading from it.

Examples

open allclose all

Basic Examples  (2)Summary of the most common use cases

Retrieve a URL and get back an HTTP response:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-8aifws
Out[1]=1

Use a second argument to get different elements of the HTTP response:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-vjiqb6
Out[1]=1

More complex requests can use HTTPRequest:

In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-ja2sq7
Out[2]=2

Scope  (2)Survey of the scope of standard use cases

Build a URL from components:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-q51c5w
Out[1]=1

Changing query parameters and scheme for a given URL:

In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-shlh3x
Out[2]=2

To specify parameters with the same name, you can use a list of rules:

In[3]:=3
✖
https://wolfram.com/xid/0dc3azq1lh46-2poj5u
Out[3]=3

Or they can be grouped in a list:

In[4]:=4
✖
https://wolfram.com/xid/0dc3azq1lh46-62ytwy
Out[4]=4

Grouping parameters in a list is useful when working with associations, since they do not allow repeated keys:

In[5]:=5
✖
https://wolfram.com/xid/0dc3azq1lh46-l05lsc
Out[5]=5

If no "Method" is specified, "GET" is used automatically:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-7cw58r
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-qlffac
Out[2]=2

The body can be a raw string:

In[3]:=3
✖
https://wolfram.com/xid/0dc3azq1lh46-07dez0
Out[3]=3

To send an HTTP request where the body is URL encoded, you can just send a list of values. If no "Method" is specified, "POST" is used automatically:

In[4]:=4
✖
https://wolfram.com/xid/0dc3azq1lh46-e4qu0y
Out[4]=4

To send files, just use the file object:

In[5]:=5
✖
https://wolfram.com/xid/0dc3azq1lh46-5ndxs1
Out[5]=5

To send a more complex file specification, you can use Association:

In[6]:=6
✖
https://wolfram.com/xid/0dc3azq1lh46-jevsjp
Out[6]=6

Content in the Association can be a string, a ByteArray, or a File:

In[7]:=7
✖
https://wolfram.com/xid/0dc3azq1lh46-b7fwp2
Out[7]=7

Options  (4)Common values & functionality for each option

CookieFunction  (1)

Apply a function to each cookie received when an HTTP response is received:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-da9j62
Out[1]=1

FollowRedirects  (1)

Specify whether to follow HTTP redirects when retrieving a URL:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-64kmq
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-48eqmb
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0dc3azq1lh46-hyx2wk
Out[3]=3

TimeConstraint  (1)

Specify the maximum allotted time in seconds to finish downloading data from the server:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-l2rf5q
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-wbzpug
Out[2]=2

VerifySecurityCertificates  (1)

Verify that the SSL certificate used by the server is valid:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-bb63uq
Out[1]=1

Properties & Relations  (3)Properties of the function, and connections to other functions

File and CloudObject are fully supported:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-f48c8p
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-i541q7
Out[2]=2

Use URLDownload to store output in a file:

In[3]:=3
✖
https://wolfram.com/xid/0dc3azq1lh46-o4ap4
Out[3]=3

Use Get for loading Wolfram Language expressions directly over HTTP:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-jid3us
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-f27qhf
Out[2]=2

Import the request by using Import or URLExecute:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-vijtc7
In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-r6tewc
In[3]:=3
✖
https://wolfram.com/xid/0dc3azq1lh46-nb5lmg
Out[3]=3
In[4]:=4
✖
https://wolfram.com/xid/0dc3azq1lh46-mz0qa0
Out[4]=4

Possible Issues  (1)Common pitfalls and unexpected behavior

Network requests can go wrong for several reasons; messages are sent to help you debug possible causes, and a Failure object is returned:

In[1]:=1
✖
https://wolfram.com/xid/0dc3azq1lh46-dsyyqy
Out[1]=1

The Failure object contains the HTTPRequest object:

In[2]:=2
✖
https://wolfram.com/xid/0dc3azq1lh46-37fmie
Out[2]=2

Neat Examples  (1)Surprising or curious use cases

Import an APIFunction:

In[11]:=11
✖
https://wolfram.com/xid/0dc3azq1lh46-cfqwn
Out[12]=12
In[10]:=10
✖
https://wolfram.com/xid/0dc3azq1lh46-oy0e0z
Out[10]=10
Wolfram Research (2016), URLRead, Wolfram Language function, https://reference.wolfram.com/language/ref/URLRead.html.
✖
Wolfram Research (2016), URLRead, Wolfram Language function, https://reference.wolfram.com/language/ref/URLRead.html.

Text

Wolfram Research (2016), URLRead, Wolfram Language function, https://reference.wolfram.com/language/ref/URLRead.html.

✖
Wolfram Research (2016), URLRead, Wolfram Language function, https://reference.wolfram.com/language/ref/URLRead.html.

CMS

Wolfram Language. 2016. "URLRead." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/URLRead.html.

✖
Wolfram Language. 2016. "URLRead." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/URLRead.html.

APA

Wolfram Language. (2016). URLRead. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/URLRead.html

✖
Wolfram Language. (2016). URLRead. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/URLRead.html

BibTeX

@misc{reference.wolfram_2025_urlread, author="Wolfram Research", title="{URLRead}", year="2016", howpublished="\url{https://reference.wolfram.com/language/ref/URLRead.html}", note=[Accessed: 04-June-2025 ]}

✖
@misc{reference.wolfram_2025_urlread, author="Wolfram Research", title="{URLRead}", year="2016", howpublished="\url{https://reference.wolfram.com/language/ref/URLRead.html}", note=[Accessed: 04-June-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_urlread, organization={Wolfram Research}, title={URLRead}, year={2016}, url={https://reference.wolfram.com/language/ref/URLRead.html}, note=[Accessed: 04-June-2025 ]}

✖
@online{reference.wolfram_2025_urlread, organization={Wolfram Research}, title={URLRead}, year={2016}, url={https://reference.wolfram.com/language/ref/URLRead.html}, note=[Accessed: 04-June-2025 ]}