# Address Insights API (India Only)

## Get Quality Information for an Address

<mark style="color:green;">`POST`</mark> `https://app.geoiq.io/addressvalidator/v1.0/validate_address_with_insights`

Shows Quality score, address components, missing components, and metadata for an address

#### Headers

| Name                                           | Type   | Description        |
| ---------------------------------------------- | ------ | ------------------ |
| x-api-key<mark style="color:red;">\*</mark>    | String | Authentication key |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json   |

#### Request Body

| Name                                        | Type   | Description                           |
| ------------------------------------------- | ------ | ------------------------------------- |
| address<mark style="color:red;">\*</mark>   | String | Address String with or without commas |
| use-cases<mark style="color:red;">\*</mark> | List   | Use case to be defined in a list      |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    "data": {
        "fraud": "Medium",
        "addressComponents": [
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "591"
                },
                "componentType": "house_no",
                "confirmationLevel": "UNCONFIRMED"
            },
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "15th main road"
                },
                "componentType": "street",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "sector 3"
                },
                "componentType": "sublocality",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "hsr layout"
                },
                "componentType": "locality",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "bangalore"
                },
                "componentType": "city",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentName": {
                    "languageCode": "en",
                    "text": "560102"
                },
                "componentType": "pincode",
                "confirmationLevel": "CONFIRMED"
            }
        ],
        "missing_components": [],
        "verdict": {
            "addressLength": 57,
            "addressScore": 100,
            "addressSyntactical": 1.0,
            "inputGranularity": "house_no",
            "multipleCityCount": 1,
            "redundancyScore": 0.066,
            "validationGranularity": "street"
        }
    },
    "message": "success",
    "status": 200
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid input, object invalid" %}

```json
{
    "message": {
        "address": "This field cannot be blank"
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Authorization Failure. Invalid key." %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Invalid Token!",
    "status": 403
}
</code></pre>

{% endtab %}
{% endtabs %}

### Response Structure

{% tabs %}
{% tab title="Success" %}

#### 200: OK

```json
{
    "data": {
        "fraud": "Medium",
        "addressComponents": [
            {
                "componentType": "house_no",
                "confirmationLevel": "UNCONFIRMED"
            },
            {
                "componentType": "street",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentType": "sublocality",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentType": "locality",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentType": "city",
                "confirmationLevel": "CONFIRMED"
            },
            {
                "componentType": "pincode",
                "confirmationLevel": "CONFIRMED"
            }
        ],
        "missing_components": [],
        "verdict": {
            "addressLength": 57,
            "addressScore": 100,
            "addressSyntactical": 1.0,
            "inputGranularity": "house_no",
            "multipleCityCount": 1,
            "redundancyScore": 0.066,
            "validationGranularity": "street"
        }
    },
    "message": "success",
    "status": 200
}
```

{% endtab %}

{% tab title="Error" %}

#### 400: Bad Request

```json
{
    "message": {
        "address": "This field cannot be blank"
    }
}
```

####

#### 403: Forbidden

```json
{
    "message": "Invalid Token!",
    "status": 403
}
```

{% endtab %}
{% endtabs %}

### Response Overview

1. **AddressComponents:** Contains an array of address components with a json object containing

<pre><code>{
<strong>    "componentType": "city",
</strong>    "confirmationLevel": "CONFIRMED"
}
</code></pre>

*where **"componentType"** is the name of the component found in the address.* \
*where **"confirmationLevel"** can be confirmed or unconfirmed.*

**NOTE**: \
**Component is Confirmed** is when the value of the component found has been confirmed by GeoIQ\
**Component is Unconfirmed** is when the value of the component found cannot be confirmed by GeoIQ

2. **Missing Components:** Contains an array of string, mentions the components not found. Possible Values are&#x20;

   * House number
   * Street
   * Locality or Sub-locality or micro-locality
   * Pincode

   **NOTE:**\
   `Locality or Sub-locality or micro-locality` is a single categor&#x79;**.** If any of these is present, we don't consider any missing. If all are missing we should show `Locality` as missing
3. **Address Score:** Score to rate the completeness of the address (Value Range - 0-100).&#x20;
4. **Address Length:** Length of the address after processing.&#x20;
5. **Redundancy Score:** Measure amount of repetitions in the address. Lower the better.&#x20;
6. **Address Syntactical:** Measure to indicate grammatical, syntactical correctness of the address. Higher the better.&#x20;
7. **Input Granularity:** The granularity of the input address. This is the result of parsing the input address and does not give any validation signals.&#x20;
8. **Validation Granularity:** The granularity level that the API can fully validate the address to.
9. **Multiple City Count:** Indicates the presence of multiple cities in the address. Ideal is 1. Higher is worse.

### Understanding Address Insights

Select the industry from the dropdown.

1. **Banking/Finance**

**Collection propensity signal** provides a signal on how likely the customer address is reachable based on Address Quality, Affluence Index by GeoIQ & Connectivity Index by GeoIQ

To understand the methodology, you can refer to [**GeoIQ: Collection Propensity Signals**](https://docs.google.com/spreadsheets/d/1LLeMOGrWlThq9gkjsOhlBmLlqj4BwXZCXe6y9i4MUD8/edit?usp=sharing)

<figure><img src="https://3504085379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3BC3mmOKUzCeeB1EAv%2Fuploads%2FsFD6zG7hoUeJ4V1XyDfW%2FScreenshot%202024-11-25%20at%203.58.19%E2%80%AFPM.png?alt=media&#x26;token=cd27d4bd-509d-431f-a62e-baf46b3dd197" alt=""><figcaption></figcaption></figure>

**Fraud signal** provides a signal on possible fraud intent in the customer address based on Address Quality.

To understand the methodology, you can refer to [**GeoIQ: Fraud Signals**](https://docs.google.com/spreadsheets/d/1_DVQKIRHIUYuc8nAi_rbSoR-ayER7tkaXcvTHqIHwlU/edit?usp=sharing)

<figure><img src="https://3504085379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3BC3mmOKUzCeeB1EAv%2Fuploads%2FbQNt0lPFP17QkRoxMPeV%2FScreenshot%202024-11-25%20at%204.04.28%E2%80%AFPM.png?alt=media&#x26;token=2c66e67d-c03c-4c46-8b9d-17a03f63b99f" alt=""><figcaption></figcaption></figure>

**Risk signal** provides a signal on Customer Risk level based on Address Quality, Affluence Index & Other GeoIQ Indices

To understand the methodology, you can refer to [GeoIQ: Risk Signals](#get-quality-information-for-an-address)

<figure><img src="https://3504085379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3BC3mmOKUzCeeB1EAv%2Fuploads%2F3LsKNwLbvLVtjjdu8K2t%2FScreenshot%202024-11-25%20at%204.08.56%E2%80%AFPM.png?alt=media&#x26;token=afedf3d3-6983-4db8-879e-4604dfc364e5" alt=""><figcaption></figcaption></figure>

### Get your API key

All API requests are authenticated using API key. Any request that doesn't include an API key will return an error.

You can get an API key from your [GeoIQ Console](https://console.geoiq.io/in/) dashboard to get started.

<figure><img src="https://3504085379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3BC3mmOKUzCeeB1EAv%2Fuploads%2FmHQRZVt948C3IpDm2ycx%2FScreenshot%202023-02-27%20at%201.03.51%20PM.png?alt=media&#x26;token=ee2c6947-2d55-4d23-b0da-f7186bcfaa3d" alt=""><figcaption></figcaption></figure>

#### Code Examples

{% tabs %}
{% tab title="cURL" %}

```
curl --location 'https://services.geoiq.io/addressvalidation' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "address": "Shades of coffee, HSR Layout,Bangalore",
  "use-cases": ["fraud"]
}'

```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = "https://services.geoiq.io/addressvalidation"

payload = json.dumps({
  "address": "Shades of coffee, HSR Layout,Bangalore",
  "use-cases": ["fraud"]
})
headers = {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
```

{% endtab %}
{% endtabs %}