CallFire Solutions

01. Query Region Information

Follow

This endpoint allows for querying and retrieving the full details of one or more regions, by accepting a series of request arguments containing a subset of region information desired. This can include such as the phone number prefix, rate center, state, and zip code. This endpoint supports the following three calls:

Endpoint

https://www.callfire.com/api/1.1/rest/number/regions

Request Type

GET

Request Headers

Content-Type application/xml
Accepts application/xml

Returns

The request returns an XML payload containing a series of region data entries matching the filters provided, if any regions did indeed match.

Request Arguments

ArgumentTypeDescription
Max Results long required - Default: 1000. The maximum number of results to return.
FirstResult long Default: 0. The starting record number for the next recordset.
Prefix string A 4-7 digit phone number prefix. A full telephone number is made up of a country code, area code, prefix, and subscriber number, for example, 1 (378) 400-1234.
City string The full name of a US city, such as Phoenix.
State string A two character state abbreviation code, such as AZ for Arizona.
Zipcode string A 5 digit, US, zip code, such as 85001 which is located in Phoenix, Arizona.
Country string An international 2 digit country code.
Lata string A 3 digit US LATA code
RateCenter string The RateCenter to use. It’s important to choose the right Rate Center, because when numbers are assigned from Rate Centers local to the premises they’ll be used at they will be deemed as local. Otherwise, there’s the risk of creating a long distance number and incurring long distance call charges.
Latitude float Filter the results returned by latitude. For example: 33.5443.
Longitude float Filter the results returned by longitude. For example: -112.049.
TimeZone string The timezone of the city which the RateCenter is in. The values which can be supplied are any that are supported by the java.util.TimeZone TimeZone.getTimeZone method. Essentially this is either an abbreviation such as “PST”, a full name such as “America/Los_Angeles”, or a custom ID such as “GMT-8:00”. Note that the support of abbreviations is for JDK 1.1.x compatibility only and full names should be used.

 

Note About FirstResult

When using this argument, the totalResults attribute in the XML payload will always display -1. Whereas, when it’s not used, then the total number of results which matched the supplied request arguments will be displayed. If this doesn’t quite make sense, refer to the two examples below.

Requests With Pagination
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="944">
Requests Without Pagination
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="-1">

Note: This is a known bug.

You can see in the examples above the difference in the attribute. We suggest that, if you’re going to implement pagination, first make a request without the FirstResult argument to get the total number of results in the result set, then pass the FirstResult argument to implement pagination of results.

Response

The elements in the response body are equivalent, where applicable, to the request arguments for the endpoint.

Example Request

The below example shows how to make a request, using a set of the available request arguments with no pagination.

curl -i https://www.callfire.com/api/1.1/rest/number/regions?MaxResults=5&City=Phoenix&State=AZ&Country=US&Lata=666 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

$requestRegionQuery = new Request\QueryRegions();
$response = $app->callfireNumberRestClient->QueryRegions($requestRegionQuery);
$result = $callfireNumberRestClient::response($response);

This example shows how to make a request, using a set of the available request arguments with pagination. This example would, in effect, is displaying 5 records per/page, and requesting the second page of results.

Curl

curl -i https://www.callfire.com/api/1.1/rest/number/regions?MaxResults=5&FirstResult\=5&City=Phoenix&State=AZ&Country=US&Lata=666 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

$requestRegionQuery = new Request\QueryRegions();
$requestRegionQuery->setTimeZone('Europe\Berlin')
    ->setMaxResults(5);
$response = $app->callfireNumberRestClient->QueryRegions($requestRegionQuery);
$result = $callfireNumberRestClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

var host = 'www.callfire.com';
var path = '/api/1.1/rest/number/regions';
var login = '24429196a2fb';
var secret = 'f992d7d671cb5b3f';
var data  = {
    MaxResults:  '5',
    City:  'Phoenix',
    State:  'AZ',
    Country:  'US',
    Lata:  '666'
};
var endpoint = '?' + querystring.stringify(data);
var options = {
    host: host,
    path: path,
    query: endpoint,
    auth: login + ':' + secret
};

var req = https.get(options, function(res) {
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/regions?",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "GET",
    RequestOptions: "MaxResults=5&City=Phoenix&State=AZ&Country=US&Lata=666",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Example Response

If there is information matching the request arguments, you can expect a response similar to the example below. It contains a Region element for each matching region found, along with the total amount of results matching the request arguments, should you wish to implement pagination over the top of the results.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="944">
      <Region>
            <Prefix>1480200</Prefix>
            <City>PHOENIX</City>
            <State>AZ</State>
            <Zipcode>85014</Zipcode>
            <Country>US</Country>
            <Lata>666</Lata>
            <RateCenter>PHOENIX</RateCenter>
            <Latitude>33.5443</Latitude>
            <Longitude>-112.049</Longitude>
            <TimeZone>America/Phoenix</TimeZone>
      </Region>
      <Region>
            <Prefix>1480201</Prefix>
            <City>PHOENIX</City>
            <State>AZ</State>
            <Zipcode>85021</Zipcode>
            <Country>US</Country>
            <Lata>666</Lata>
            <RateCenter>PHOENIX</RateCenter>
            <Latitude>33.5443</Latitude>
            <Longitude>-112.049</Longitude>
            <TimeZone>America/Phoenix</TimeZone>
      </Region>
</r:ResourceList>

 

Have more questions? Submit a request

Comments