({{, (RefLink[URLRead, paclet:ref/URLRead])[url] 
sends a request to a URL and reads back the response, returning it as a response object.}, {, (RefLink[URLRead, paclet:ref/URLRead])[assoc]
sends a request to a URL built from an association of components and metadata elements.}, {, (RefLink[URLRead, paclet:ref/URLRead])[(RefLink[HTTPRequest, paclet:ref/HTTPRequest])[…]]
sends a request specified by a symbolic (RefLink[HTTPRequest, paclet:ref/HTTPRequest]) object.}, {, (RefLink[URLRead, paclet:ref/URLRead])[req,"elem"]
returns only the element elem from the response.}, {, (RefLink[URLRead, paclet:ref/URLRead])[req,{"(Subscript[elem, 1])","(Subscript[elem, 2])",…}]
returns an association of the values of the elements (Subscript[elem, i]).}, {, (RefLink[URLRead, paclet:ref/URLRead])[{(Subscript[req, 1]),(Subscript[req, 2]),…},…]
sends the requests (Subscript[req, i]) in parallel, giving a list of the results obtained.}})

OpenersNotesSection(Spacer1)Details and Options

In (RefLink[URLRead, paclet:ref/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:

The following additional entries can also be included in the association, as in (RefLink[HTTPRequest, paclet:ref/HTTPRequest]):

The setting for "Body" can have the following forms:

Detailed specifications for each part in a multipart encoding are given as an association with the following elements:

The setting "Cookies"->(RefLink[Automatic, paclet:ref/Automatic]) specifies that cookies from (RefLink[$Cookies, paclet:ref/$Cookies]) for the domain corresponding to url should be sent. "Cookies" can also give an explicit list of associations representing cookies. "Cookies"->(RefLink[None, paclet:ref/None]) specifies that no cookies should be sent.

The default "UserAgent" is typically "Wolfram HTTP Client xxxx", where xxxx is a version number.

The setting for "Headers" can be a list of rules or an association.

In (RefLink[URLRead, paclet:ref/URLRead])[req,elem], the following elements can be used:

(RefLink[URLRead, paclet:ref/URLRead]) supports the following options:

The setting (RefLink[CharacterEncoding, paclet:ref/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 (RefLink[CharacterEncoding, paclet:ref/CharacterEncoding])->(RefLink[None, paclet:ref/None]) specifies that no change should be made to strings before sending them to the server.

With (RefLink[CharacterEncoding, paclet:ref/CharacterEncoding])->(RefLink[Automatic, paclet:ref/Automatic]), the encoding is taken from the "ContentType" element if this is specified; otherwise, the encoding is "UTF8".

(RefLink[TimeConstraint, paclet:ref/TimeConstraint])->t allows a maximum of t seconds for connection to the URL and reading from it.

(RefLink[TimeConstraint, paclet:ref/TimeConstraint])-><|"Connecting"->(Subscript[t, c]),"Reading"->(Subscript[t, r])|> specifies separate timeouts for connecting to the URL and reading from it.

OpenersPrimaryExamplesSection(Spacer1)Examples  (13)

OpenersExampleSection0(Spacer1)Basic Examples  (2)

Retrieve a URL and get back an HTTP request:

URLRead["http://wolfram.com"]

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

URLRead["http://wolfram.com", {"StatusCode", "Headers"}]

More complex requests can use (RefLink[HTTPRequest, paclet:ref/HTTPRequest]):

URLRead[HTTPRequest["http://wolfram.com", <|"Method" -> "POST"|>]]

OpenersExampleSection1(Spacer1)Scope  (2)

Build a URL from components:

URLRead[\[LeftAssociation]"Scheme"->"http","Domain"->"www.wolframalpha.com","Query"->{"i"->"200 usd in eur"}\[RightAssociation]]

Changing query parameters and scheme for a given (RefLink[URL, paclet:ref/URL]):

HTTPRequest[URL["http://www.wolframalpha.com/"], <|"Query"-> {"i" -> "200 usd in eur"}, "Scheme" -> "https"|>]

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

HTTPRequest["http://example.com", <|"Query" -> {"a" -> "1", "a" -> "2"}|>]

Or they can be grouped in a list:

HTTPRequest["http://example.com", <|"Query" -> {"a" -> {"1", "2"}}|>]

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

HTTPRequest["http://example.com", <|"Query" -> <|"a" -> {"1", "2"}|>|>]

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

url = CloudDeploy[Delayed[HTTPRequestData[{"Method","FormRules"}], "WL"]];

URLRead[url, "Body"]

The body can be a raw string:

req = HTTPRequest[
url, <|
Method -> "POST", 
"Body"-> "x=2",
"ContentType" -> "application/x-www-form-urlencoded"
|>
];
URLRead[req, "Body"]

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:

req = HTTPRequest[url, <|"Body" -> {"x" -> {1, 2, 3}}|>];
URLRead[req, "Body"]

To send files, just use the file object:

image = FindFile["ExampleData/Ocelot.jpg"];
req = HTTPRequest[url, <|"Body"->{"image" -> File[image]}|>];
URLRead[req, "Body"]

To send a more complex file specification, you can use (RefLink[Association, paclet:ref/Association]):

req = HTTPRequest[url, <|
"Body"->{"image" -> <|"Content" -> "hello world","MIMEType" -> "text/plain","Name" -> "mycustomname.txt"|>}
|>];
URLRead[req, "Body"]

Content in the (RefLink[Association, paclet:ref/Association]) can be a string, a (RefLink[ByteArray, paclet:ref/ByteArray]), or a (RefLink[File, paclet:ref/File]):

image = FindFile["ExampleData/Ocelot.jpg"];
req = HTTPRequest[url, <|
"Body"->{"image" -> <|"Content" -> File[image],"MIMEType" -> "image/jpeg","FileName" -> "my-custom-ocelot.jpeg"|>, "bytes" -> <|"Content" -> ToCharacterCode["hello world"], "Name" -> "my-inmemory-file-upload.txt", "MIMEType" -> "text/plain"|>, "string" -> "just a string"}
|>];
URLRead[req, "Body"]

OpenersExampleSection2(Spacer1)Options  (4)

OpenersExampleSubsection0(Spacer1)VerifySecurityCertificates  (1)

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

URLRead["https://wolfram.com", "StatusCode",VerifySecurityCertificates -> True]

OpenersExampleSubsection1(Spacer1)CookieFunction  (1)

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

URLRead["http://wolfram.com/", "StatusCode", CookieFunction->Print]

OpenersExampleSubsection2(Spacer1)TimeConstraint  (1)

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

api = CloudDeploy[Delayed[Pause[10]]];

URLRead[api, TimeConstraint->1]

OpenersExampleSubsection3(Spacer1)FollowRedirects  (1)

Specify whether to follow HTTP redirects when retrieving a URL:

url = URLShorten["http://wolfram.com"]

URLRead[url, FollowRedirects->False]

URLRead[url, FollowRedirects->True]

OpenersExampleSection3(Spacer1)Properties & Relations  (3)

(RefLink[File, paclet:ref/File]) and (RefLink[CloudObject, paclet:ref/CloudObject]) are fully supported:

HTTPRequest[URL["http://wolfram.com"], <|"Query" -> {"x" -> {1, 2, 3}}|>]

HTTPRequest[CloudObject[], <|"Query" -> {"x" -> {1, 2, 3}}|>]

Use (RefLink[URLDownload, paclet:ref/URLDownload]) to store output in a file:

URLDownload[HTTPRequest[URL["http://wolfram.com"]]]

Use (RefLink[Get, paclet:ref/Get]) for loading Wolfram Language expressions directly over HTTP:

Get["http://exampledata.wolfram.com/Collatz.m"]

Collatz[5]

Import the request by using (RefLink[Import, paclet:ref/Import]) or (RefLink[URLExecute, paclet:ref/URLExecute]):

api = CloudDeploy[APIFunction[{"text" -> "String" -> "Hello"}, ImageResize[Graphics[{Circle[],Text[Style[#text, 40],{0,0}]}], 100] &, "PNG"]];

req = HTTPRequest[api];

Import[req]

URLExecute[req, {"text" -> "Ciao"}]

OpenersExampleSection4(Spacer1)Possible Issues  (1)

Network requests can go wrong for several reasons; messages are sent to help you debug possible causes, and a (RefLink[Failure, paclet:ref/Failure]) object is returned:

response = URLRead["http://notanurl.com"]

The (RefLink[Failure, paclet:ref/Failure]) object contains the (RefLink[HTTPRequest, paclet:ref/HTTPRequest]) object:

response[[2, "HTTPRequest"]]

OpenersExampleSection5(Spacer1)Neat Examples  (1)

(RefLink[Import, paclet:ref/Import]) an (RefLink[APIFunction, paclet:ref/APIFunction]):

api=CloudDeploy[APIFunction["x"->"Country",GeoGraphics[#x]&,"PNG"]];
response = URLRead@HTTPRequest[api, <|"Query" -> {"x" -> "France"}|>]

Import[response]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[URLExecute, paclet:ref/URLExecute])  ▪  (RefLink[URLDownload, paclet:ref/URLDownload])  ▪  (RefLink[URLSubmit, paclet:ref/URLSubmit])  ▪  (RefLink[Import, paclet:ref/Import])  ▪  (RefLink[HTTPRequest, paclet:ref/HTTPRequest])  ▪  (RefLink[HTTPResponse, paclet:ref/HTTPResponse])  ▪  (RefLink[SocketConnect, paclet:ref/SocketConnect])  ▪  (RefLink[URLResponseTime, paclet:ref/URLResponseTime])  ▪  (RefLink[PingTime, paclet:ref/PingTime])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Web Operations, paclet:guide/WebOperations])}, {▪(RefLinkPlain[HTTP Requests & Responses, paclet:guide/HTTPRequestsAndResponses])}, {▪(RefLinkPlain[URL Manipulation, paclet:guide/URLManipulation])}, {▪(RefLinkPlain[Web Browser Automation, paclet:guide/WebBrowserAutomation])}, {▪(RefLinkPlain[Using Connected Devices, paclet:guide/UsingConnectedDevices])}, {▪(RefLinkPlain[Cookie Management, paclet:guide/CookieManagement])}, {▪(RefLinkPlain[Cloud Functions & Deployment, paclet:guide/CloudFunctionsAndDeployment])}, {▪(RefLinkPlain[Network Programming, paclet:guide/NetworkProgramming])}})}})