API to return the cloud provider and region for a given IPv4 address or hostname. Multiple results may be returned - some subnet scopes overlap.
A webpage page that consumes the API is published to the root of the website. Connect to the website root for an example page using this API. e.g. http://127.0.0.1
The API provides the following path based parameters:
GET http://127.0.0.1/api/hostname/{hostname}
hostname <string> : The DNS name or IPv4 address of the cloud service.
e.g. curl http://127.0.0.1/api/hostname/34.37.1.5
e.g. curl http://127.0.0.1/api/hostname/example.com
No authentication required.
A 200 response code returned on success with the following JSON payload:
[
{
"IPAddress": <string>,
"Subnet": <string>,
"Region": <string>,
"Service": <string>,
"SubnetSize": <string>,
"CloudProvider": <string>
}
]A 404 response code is returned on failure with the following JSON payload containing the error message:
{
"Message": <string>
}[
{
"IPAddress": "34.37.1.5",
"Subnet": "34.37.0.0/16",
"Region": "us-west8",
"service": "Google Cloud",
"SubnetSize": "16",
"CloudProvider": "Google Cloud"
}
]Multiple results may be returned.
- DNS names may resolve to multiple IP addresses.
- Some cloud providers include super nets and smaller subnets that a given IP may match both.
- The same subnet is repeated with different service tags. e.g:
[
{
"IPAddress": "3.16.2.15",
"Subnet": "3.16.0.0/14",
"region": "us-east-2",
"service": "AMAZON",
"SubnetSize": "14",
"CloudProvider": "AWS"
},
{
"IPAddress": "3.16.2.15",
"Subnet": "3.16.0.0/14",
"region": "us-east-2",
"service": "EC2",
"SubnetSize": "14",
"CloudProvider": "AWS"
}
]Failure example:
{
"Message": "DNS lookup failed"
}Returns all IPv4 subnets for the specified cloud provider.
GET http://127.0.0.1/api/subnets/{CloudProvider}
CloudProvider <string> : The name of the specific cloud provider. Must be one of "AWS", "Azure", "AzureGovernment", AzureChina", "AzureGermany", "OCI", "GoogleCloud", "DigitalOcean", "Akamai", or "CloudFlare"
e.g. curl http://127.0.0.1/api/subnets/aws
e.g. curl http://127.0.0.1/api/subnets/azure
No authentication required.
A 200 response code will be returned on success. Results returned as a JSON payload. All subnet ranges associated with the specified cloud provider will be returned. The JSON payload will be and array of objects of the following format:
[
{
"Subnet": <string>,
"Region": <string>,
"Service": <string>,
"SubnetSize": <string>,
"CloudProvider": <string>
}
]On failure a 404 response code is returned the following JSON payload containing the error message:
{
"Message": <string>
}Example response is truncated for brevity.
[
{
"Subnet": "209.199.34.0/25",
"Region": "",
"Service": "",
"SubnetSize": "25",
"CloudProvider": "Azure"
},
{
"Subnet": "209.199.34.128/25",
"Region": "",
"Service": "",
"SubnetSize": "25",
"CloudProvider": "Azure"
},
{
"Subnet": "209.199.35.0/25",
"Region": "",
"Service": "",
"SubnetSize": "25",
"CloudProvider": "Azure"
},
{
"Subnet": "213.199.169.0/24",
"Region": "",
"Service": "",
"SubnetSize": "24",
"CloudProvider": "Azure"
}
.
.
.
]Displays information about the client connection.
GET http://127.0.0.1/api/info
None.
e.g. curl http://127.0.0.1/api/info
No authentication required.
Client information returned as a JSON payload
{
"BuildDate": <string>,
"ClientIP": <string>,
"Protocol": <string>,
"HTTPVersion": <string>,
"Headers": <object> {
}
}{
"BuildDate": "12-March-2025",
"ClientIP": "::ffff:127.0.0.1",
"Protocol": "http",
"HTTPVersion": "1.1",
"Headers": {
"host": "127.0.0.1",
"user-agent": "curl/8.10.1",
"accept": "*/*"
}
}IP ranges and region details for each cloud provider are sourced from:
- AWS: https://ip-ranges.amazonaws.com/ip-ranges.json
- Azure (Public): https://www.microsoft.com/en-us/download/confirmation.aspx?id=56519
- Azure (Government): https://www.microsoft.com/download/details.aspx?id=57063
- Azure (China): https://www.microsoft.com/download/details.aspx?id=57062
- Azure (Germany): https://www.microsoft.com/download/details.aspx?id=57064
- Google Cloud: https://www.gstatic.com/ipranges/cloud.json
- Oracle CLoud: https://docs.oracle.com/en-us/iaas/tools/public_ip_ranges.json
- Digital Ocean: https://digitalocean.com/geo/google.csv
- CloudFlare: https://www.cloudflare.com/ips-v4/#
- Akamai: https://ipinfo.io/widget/demo/akamai.com?dataset=ranges
$ git clone https://github.com:RobHolme/CloudRegionAPI.git
$ cd CloudRegionAPI
$ npm install express @types/express --save
$ npm install --only=dev
The repo files are updated 12am every Sunday via a GitHub action, so this step can be skipped unless the very latest updates are needed.
Requires powershell 7 (or greater) to run the script. If building on Windows, do not use Powershell 5.1 as the performance will be exceedingly slow.
$ pwsh -File ./update-cloudprovidersjson.ps1
$ node --run build
$ node --run serve
$ npm install express @types/express --save
$ npm install --only=dev$ git clone https://github.com:RobHolme/CloudRegionAPI.git
$ cd CloudRegionAPI
Requires powershell 7 (or greater) to run the script. If building on Windows, do not use Powershell 5.1 as the performance will be exceedingly slow.
If this script isn't run the API will use the potentially older versions of the JSON files included in the repo.
$ pwsh -File ./update-cloudprovidersjson.ps1
$ sudo ./build-container.sh$ sudo docker run --name CloudRegionAPI --publish 80:80 --env NODE_ENV=production --detach robholme/cloud-region-api:latest
$ sudo docker run --name CloudRegionAPI --publish 80:80 --env NODE_ENV=production --detach ghcr.io/robholme/cloud-region-api:latest