> For the complete documentation index, see [llms.txt](https://docs.plumvoice.com/voicetrends/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plumvoice.com/voicetrends/voicetrends-api/geographic.md).

# Geographic

{% hint style="success" %}
**- NEW! - Interactive API docs, now live!**

Visit [api-docs.plumvoice.com](https://api-docs.plumvoice.com/) to **read** Plum API documentation, **build and test requests** in our interactive API sandbox, **review** the responses, and **share** it all with your team.
{% endhint %}

## Caller Profile Data

<mark style="color:blue;">`GET`</mark> `https://voicetrends.plumvoice.com/api/profile/{start}/{end}/{phone}`

This service fetches any of the available data in the Caller Profile/Geographic page in VoiceTrends. To use this service, provide your temporary authentication credentials and several GET parameters, which function as filters for this data. This API is rate-limited in a group with all other raw data resources to 150 requests per 15-minute window.

#### Path Parameters

| Name  | Type    | Description                                                                        |
| ----- | ------- | ---------------------------------------------------------------------------------- |
| start | integer | The start date (inclusive) for this request in YYYYMMDD format.                    |
| end   | integer | The end date (inclusive) for this request in YYYYMMDD format.                      |
| phone | string  | The single phone number for this report or “ALL” to merge data across all numbers. |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
HTTP/1.1 200 OK
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 146
X-RateLimit-Reset: 1519671600
Content-Length: 394
Content-Type: application/json

{
  "US":{
    "AL":0,
    "AK":0,
    "AZ":0,
    "AR":0,
    "CA":0,
    "CO":0,
    "CT":0,
    "DC":0,
    "DE":0,
    "FL":0,
    "GA":0,
    "HI":0,
    "ID":0,
    "IL":0,
    "IN":0,
    "IA":0,
    "KS":0,
    "KY":0,
    "LA":0,
    "ME":0,
    "MD":0,
    "MA":0,
    "MI":0,
    "MN":0,
    "MS":0,
    "MO":0,
    "MT":0,
    "NE":0,
    "NV":0,
    "NH":0,
    "NJ":0,
    "NM":0,
    "NY":0,
    "NC":0,
    "ND":0,
    "OH":0,
    "OK":0,
    "OR":0,
    "PA":0,
    "RI":0,
    "SC":0,
    "SD":0,
    "TN":0,
    "TX":0,
    "UT":0,
    "VT":0,
    "VA":0,
    "WA":0,
    "WV":0,
    "WI":0,
    "WY":0,
    "US Toll-Free":1
  },
  "NON_US":[]
}
```

{% endtab %}

{% tab title="XML" %}

```markup
< HTTP/1.1 200 OK
< Date: Mon, 26 Feb 2018 18:54:45 GMT
< Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/1.0.2d PHP/5.4.45
< X-Powered-By: PHP/5.4.45
< X-RateLimit-Limit: 150
< X-RateLimit-Remaining: 145
< X-RateLimit-Reset: 1519671600
< Content-Length: 2772
< Content-Type: application/xml
< 
<?xml version="1.0"?>
<result>
  <US>
    <item><location>AL</location><count>0</count></item>
    <item><location>AK</location><count>0</count></item>
    <item><location>AZ</location><count>0</count></item>
    <item><location>AR</location><count>0</count></item>
    <item><location>CA</location><count>0</count></item>
    <item><location>CO</location><count>0</count></item>
    <item><location>CT</location><count>0</count></item>
    <item><location>DC</location><count>0</count></item>
    <item><location>DE</location><count>0</count></item>
    <item><location>FL</location><count>0</count></item>
    <item><location>GA</location><count>0</count></item>
    <item><location>HI</location><count>0</count></item>
    <item><location>ID</location><count>0</count></item>
    <item><location>IL</location><count>0</count></item>
    <item><location>IN</location><count>0</count></item>
    <item><location>IA</location><count>0</count></item>
    <item><location>KS</location><count>0</count></item>
    <item><location>KY</location><count>0</count></item>
    <item><location>LA</location><count>0</count></item>
    <item><location>ME</location><count>0</count></item>
    <item><location>MD</location><count>0</count></item>
    <item><location>MA</location><count>0</count></item>
    <item><location>MI</location><count>0</count></item>
    <item><location>MN</location><count>0</count></item>
    <item><location>MS</location><count>0</count></item>
    <item><location>MO</location><count>0</count></item>
    <item><location>MT</location><count>0</count></item>
    <item><location>NE</location><count>0</count></item>
    <item><location>NV</location><count>0</count></item>
    <item><location>NH</location><count>0</count></item>
    <item><location>NJ</location><count>0</count></item>
    <item><location>NM</location><count>0</count></item>
    <item><location>NY</location><count>0</count></item>
    <item><location>NC</location><count>0</count></item>
    <item><location>ND</location><count>0</count></item>
    <item><location>OH</location><count>0</count></item>
    <item><location>OK</location><count>0</count></item>
    <item><location>OR</location><count>0</count></item>
    <item><location>PA</location><count>0</count></item>
    <item><location>RI</location><count>0</count></item>
    <item><location>SC</location><count>0</count></item>
    <item><location>SD</location><count>0</count></item>
    <item><location>TN</location><count>0</count></item>
    <item><location>TX</location><count>0</count></item>
    <item><location>UT</location><count>0</count></item>
    <item><location>VT</location><count>0</count></item>
    <item><location>VA</location><count>0</count></item>
    <item><location>WA</location><count>0</count></item>
    <item><location>WV</location><count>0</count></item>
    <item><location>WI</location><count>0</count></item>
    <item><location>WY</location><count>0</count></item>
    <item><location>US Toll-Free</location><count>1</count>
    </item>
  </US>
  <NON_US/>
</result>
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1519659000
Content-Length: 90
Content-Type: application/json

{"error":"Invalid start parameter."}
```

{% endtab %}

{% tab title="XML" %}

```markup
HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1519659000
Content-Length: 120
Content-Type: application/json

<?xml version="1.0"?>
<result>
  <error>Invalid start parameter.</error>
</result>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### **Possible Response Codes**

* **200**: success, data successfully returned.
* **400**: supplied data improperly formatted or invalid
* **401**: authentication parameters invalid or the account is inactive
* **405**: invalid HTTP method supplied (only POST allowed)
* **429**: rate limit exceeded
* **500**: unknown error

The return structure will contain the following item(s):

| Name    | Data Type | Always Present | Description                                                                                       |
| ------- | --------- | -------------- | ------------------------------------------------------------------------------------------------- |
| error   | string    | no             | Indicates what went wrong when an HTTP code other than 200 is returned.                           |
| US      | array     | no             | A 200 HTTP code returns this value, the list of US locations and their associated call count.     |
| NON\_US | array     | no             | A 200 HTTP code returns this value, the list of non-US locations and their associated call count. |

### **Sample Code**

This sample code makes a request to authenticate an account using PHP, but any language capable of integrating with a REST API works for this type of request:

```php
<?php
// authentication and filter settings
$login = '<your_temporary_login>';
$password = '<your_temporary_password>';
$start = '<start_date>';
$end = '<end_date>';
$phone = '<selected_phone_number>';

// build the URL
$url = 'https://voicetrends.plumvoice.com/api/performance/'.$start.'/'.$end.'/'.$phone;

$ch = curl_init();
curl_setopt($ch, CURLOPT_USERPWD, $login.':'.$password);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);
```