The interface will return all the dial rules for a given country in JSON format, which can then be used in your own scripts or application.
To access the API, you simply construct the URL to correspond to the correct representation for the desired country. The base URL for the JSON interface starts with:
https://www.ucdialplans.com/queryapi/
You then add specific options as query strings. For NANPA countries like US, Canada and many Caribbean countries, use the following:
Query String
|
Data Value
|
Required?
|
countrycode
|
1
|
Yes
|
npa
|
3-digit integer
|
Yes
|
nxx
|
3-digit integer
|
Yes
|
natscope
|
national/uscan/all
|
No (defaults to national)
|
sevendigit
|
yes/no;1/0;true/false
|
No (defaults to no)
|
apikey
|
16-character alphanumeric
|
Yes
|
For an example location in Chicago, where we want to treat both US and Canada numbers as national numbers, use the following:
For any other country, the available query strings are as follows:
https://www.ucdialplans.com/queryapi/?countrycode=1&npa=312&nxx=226&natscope=uscan&apikey=yourapikeyhere
For any other country, the available query strings are as follows:
Query String
|
Data Value
|
Required?
|
countrycode
|
1-3 digit integer value
|
Yes
|
areacode
|
1-6 digit integer value
|
Most countries
|
carriercode
| 1-3 digit integer value | Some countries |
apikey
|
16-character alphanumeric
|
Yes
|
For example, to return the dial rules for London, UK use the following URL:
https://www.ucdialplans.com/queryapi/?countrycode=44&areacode=20&apikey=yourapikeyhereThe results will look something like this, when you parse it through a JSON formatter:
One way to use this data is in your own personal PowerShell script. Below is an example that will pull down the dial rules for 312-226 in Chicago:
$DialPlan = "https://www.ucdialplans.com/queryapi/?countrycode=1&npa=312&nxx=226&apikey=abc1234567890xyz"Once you've got the JSON data, you can return specific elements simply by "following the path", as it were:
$JSON = Invoke-RestMethod -Method Get -Uri $DialPlan
PS C:\> $JSON.data.routes
local : {@{pattern=^\+1((872([^01]\d\d))|(847([^01]\d\d))...
tollfree : @{pattern=^\+18(00|8\d|77|66|55|44|33|22)\d{7}$}premium : @{pattern=^\+1(900|976)[2-9]\d{6}$}national : @{pattern=^\+1(?!(24[26]|26[48]|284|345|441|473|649|664|721|[67]58|767|784|8[024]9|86[89]|876|900|976)) [2-9]\d\d[2-9]\d{6}$}international : @{pattern=^\+((1(?!(900|976))[2-9]\d\d[2-9]\d{6})|([2-9]\d{6,14}))}service : @{pattern=^\+?([2-9]11)$}
You can get as specific as you want:
PS C:\> $JSON.data.normrules.national.pattern^1?([2-9]\d\d[2-9]\d{6})\d*(\D+\d+)?$PS C:\> $JSON.data.routes.international.pattern^\+((1(?!(900|976))[2-9]\d\d[2-9]\d{6})|([2-9]\d{6,14}))For elements that could have multiple values, such as local routes, you have to write it a little bit differently (note the square brackets):
PS C:\> $JSON.data.routes.local[0].pattern^\+1((872([^01]\d\d))|(847([^01]\d\d))|(815(20[^189]|21[^1378]|22[01348]|23[067]|24[125]|25[02458]|26[^2469]|27[^035]|28[07]|29[0345]|30[^39]|31[03478]|32[^39]|33[^2569]|34[^0]|35[^089]|36[1346]|37[^5689]|38[23568]|40[^026]|41[^149]|42[^089....You must also include a valid API key. For testing purposes, I've created a demo API key that anybody can use.
The output will be obfuscated to deter abuse, but is otherwise valid JSON. Please give it a try, and if you feel there is a place for this in your company or application, please contact me through the usual channels.abc1234567890xyz
The APIs have been documented on SwaggerHub, where you can check them out and even run tests to see what the output looks like.
I have to give thanks to longtime SfB/Teams MVP Jonathan McKinney for pushing me to do this, and to help test it along the way. Beers are inbound!
