Parse URL
URL Parse API documentation
The URL Parse API makes it easy to parse a URL.
The URL Parse API is a 'REST API' which is accessible via HTTPS using the GET or POST method at a predefined URL and returns a JSON response.
Benefits of using the URL Parse API are:
- Querying the URL Parse API is free of charge and anonymous.
- The URL Parse API works across applications and scripting languages, e.g. see below the Python example.
This URL Parse API is coded and provided by ex-Google engineer and technical SEO expert Fili.
Authentication
This URL Parse API is free of charge and can be accessed without credentials. If you have any questions about using the URL Parse API on a larger scale or like to discuss ways to utilize this database internally, contact Fili.
Currently the URL Parse API is rate-limited to 1000 requests/hour for each IP address. If you need more, contact Fili.
Optimize your URL Parse API GET requests and avoid hitting the rate-limits by locally caching 200 status responses from the URL Parse API for at least 6 hours before resubmitting a duplicate query to the URL Parse API.
Quickstart guide
GET request
You can query the URL Parse API endpoint using a GET request and replace URL with the URL you wish to parse.
https://api.urlparse.com/v1/query?url=URL
The following URL parameter is required for GET requests to the URL Parse API:
URL Parameter | Value |
---|---|
url | (string) representing an encoded URL |
POST request
Alternatively, you can also query the URL Parse API endpoint using a POST request on the following URL:
https://api.urlparse.com/v1/query
With the POST body containing the URL to parse in JSON (replace URL with the URL you wish to parse).
{
"url": "URL"
}
Endpoint definitions
The endpoint of the URL Parse API is:
https://api.urlparse.com/v1/query
By default the URL Parse API will return a JSON response like:
{
"authority": "urlparse.com",
"domain": "urlparse.com",
"domain_label": "urlparse",
"file": "/",
"fragment": null,
"host": "urlparse.com",
"href": "https://urlparse.com/",
"is_valid": true,
"origin": "https://urlparse.com",
"params": null,
"path": "/",
"port": null,
"query": null,
"request_url": "https://urlparse.com",
"scheme": "https",
"subdomains": null,
"tld": "com"
}
When the URL queried is invalid or incomplete, the JSON response may look like:
{
"error": "Unparseable URL.",
"is_valid": false,
"request_url": "example"
}
Percent-encoding
Any URL submitted for parsing through a GET request has to be encoded, in particular replace the following symbols:
Character | Percent-Encoding |
---|---|
# | %23 |
% | %25 |
& | %26 |
@ | %40 |
space | %20 |
Response status codes
The URL Parse API will respond (most of the time) with any of the following status codes:
HTTP status code | Reason | Body content |
---|---|---|
200 | Success | JSON response with parsed URL data. |
400 | Bad request | Unable to validate: JSON response with error message. |
422 | Unprocessable Entity | Invalid URL: JSON response with error message. |
429 | Too many requests | Rate-limiting: Reduce the number of requests per hour. |
500 | Server error | Unknown error occured on the server side, please try later again. |
Python example
It is possible to use the URL Parse API in your code with Python or similar other languages, using POST or GET requests.
GET request
import requests
r = requests.get(
'https://api.urlparse.com/v1/query?url=https://example.re/'
)
POST request
import requests
r = requests.post(
'https://api.urlparse.com/v1/query',
json={'url': 'https://example.re/'}
)
JSON response
Both the POST or GET request examples above will return with the following JSON response:
print(r.json())
{
'authority': 'example.re',
'domain': 'example.re',
'file': '/',
'fragment': None,
'host': 'example.re',
'href': 'https://example.re/',
'is_valid': True,
'label': 'example',
'origin': 'https://example.re',
'params': None,
'path': '/',
'port': None,
'query': None,
'request_url': 'https://example.re/',
'scheme': 'https',
'subdomains': None,
'tld': 're'
}
cURL example
It is possible to submit POST or GET requests on the command line, e.g. using cURL, to access the URL Parse API.
GET request
curl https://api.urlparse.com/v1/query?url=https://example.re/
POST request
curl -X POST https://api.urlparse.com/v1/query \
-H 'Content-Type: application/json' \
-d '{"url": "https://example.re/"}'
JSON response
Both the POST or GET request examples above will return with the following JSON response:
{
'authority': 'example.re',
'domain': 'example.re',
'file': '/',
'fragment': None,
'host': 'example.re',
'href': 'https://example.re/',
'is_valid': True,
'label': 'example',
'origin': 'https://example.re',
'params': None,
'path': '/',
'port': None,
'query': None,
'request_url': 'https://example.re/',
'scheme': 'https',
'subdomains': None,
'tld': 're'
}
Disclaimer
The URL Parse API on this website is under constant development and improvements will be added over time. Any data and/or query submitted to this website or its API is only used to verify whether a URL validates. When the URL validates, the URL (or any other submitted data) is after returning the result completely disregarded and ignored. Only if a URL does not validate, the URL may be temporarily stored for debugging purposes, afterwhich the URL (or any other submitted data) is still completely disregarded and ignored.
Bugs will happen. Despite best efforts to maintain the code base and data quality, no guarantees can or will be given. Data may be incomplete and/or errors may occur. This is a personal website and for-fun project. Use at your own risk.