What are URLs?

URL stands for Uniform Resource Locator, and is a way to reference a resource like a web page on the internet (or any network). A URL is such a ubiquitous aspect of the internet yet there is probably more to a URL and its components than you've yet considered.

URL composition

Consider this sample URL, which actually constitutes a valid request to our US Street Address API (line breaks have been added for clarity):

https://us-street.api.smarty.com/street-address
?auth-id=123&auth-token=abc&
street=1600+amphitheatre+pkwy+mountain+view+ca

We can decompose this URL into smaller components:

Scheme: https

The first part of the URL is the scheme. Among the many officially registered schemes are the familiar http and https schemes. They both specify that the resource requested by the URL are to be served via the HTTP protocol, but https is a secure, two-way transfer of information. We value security and your privacy and so our APIs only respond to requests with an https URL scheme.

Hostname: us-street.api.smarty.com

This part of the URL is what gets your request to our API servers, as opposed to Google's servers, or any other server on the internet. Note the colon and slashes (://) that separate the scheme from the hostname.

Path: /street-address

Often, the same servers (or group of servers) that are identified by a hostname provide different resources. The way you access those specific resources is through a path.

Query string:

?auth-id=123&auth-token=abc&street=1600+amphitheatre+pkwy+mountain+view+ca

API requests require that authentication information (auth-id and auth-token) be encoded in the query string of the URL. See our authentication documentation for more details. If submitting a GET request, the address input (street) will also be encoded in the query string. Consult the specific API documentation for your use case for more information on what inputs to submit. In some situations you may need to use the optional license query string parameter. See our License Selection page for guidance.

Is that it?

We should mention that there are additional URL components that are not required when sending requests to our APIs such as the port number and the fragment identifier. We'll leave those discoveries as an exercise for the reader.

In conclusion, URLs communicate several pieces of vital information, without which, API requests would fail, emails would surely go unread, and, worse yet, cat videos would cease to load. So, the next time you visit a website, take a moment to appreciate the compact information contained within the address bar of your web browser.