Overview
This document is a guide on how to use Dvsum Address Validation API. Dvsum Address Validation API helps the users to validate their address data thus getting a clean and more meaningful and understandable address.
In this document, we will learn the following things:
- Dvsum Address Validation API endpoint: The REST endpoint to access the amazing Address Validation functionality
- The HTTP method to ping this endpoint.
- Request Format: The format in which the data is to be sent to the API.
- Response Format: The format in which the API will return the validated results.
- Error Codes: If some error occurs, error codes help to know what kind of error it is.
URL
https://apis.dvsum.com/address-validation
Method
The request type is POST.
Authentication Header
Request header should contain the following header.
- x-api-key: <api-key-value>
Request Payload
The address data needs to be sent to API in the request body of the POST request. Following is the structure of how the request body is to be created.
{
"addresses": [
{
"address_line1": "",
"city": "",
"zip_code": "",
"country": "",
"company_name": "",
"address_line2": "",
"address_line3": "",
"state": "",
"other_address_lines": ""
}
],
"case_format": "",
"zip_code_format": ""
}
Now, let us dig deep into each of these fields.
“addresses” (mandatory) contains the address data that is to be validated. It can contain the following fields. |
“address_line1” mainly contains the data of the street i.e., street number and street name. However, it can also contain the data that one is supposed to enter in “address_line2” and “address_line3”. |
“city” contains name of the city. |
“zip_code” contains zip code. It can be added either in US format or non-US format. |
“country” preferably contains abbreviated name of the country; however, full name can also be provided but in that case matched status will be |
“address_line2” (optional) contains the data of Suite/Apartment/Building. |
“address_line3” (optional) contains c/o information and attention. |
“state” (optional) preferably contains abbreviated name of the state or province, however, full name can also be provided but in that case matched status will be For example, if user wants to enter New York, he/she should enter NY rather than the full name. |
“case_format” (optional) represents the case format in which the results are to be returned. It can have any of these three values,
case_format is an optional field. Hence, if not provided, its default value will apply which will return results in InitCap format. For example, the street address “4000 KRESGE WAY REC DOCK” will be converted to “4000 Kresge Way Rec Dock”. Here, you can see that the first letter of each word is in uppercase and the rest are in lowercase. For OK result API is doing case sensitive check which means input address is exactly same as matched one then it is considering as ok. Any case change or standardization (Road to Rd) consider as Standardize. |
“zip_code_format” (optional) represents the Zip code format in which the results are to be returned. For US, zip code format can have any of these two values,
For non-US, zip code format might not be provided. API will validate it and might add a whitespace. For example, L5T2N7 will get converted to L5T 2N7. In this case, matched status will be standardized. zip_code_format is an optional field. Hence, if not provided “FULL” will be used as its value. |
Note:
- All the field names are to be provided in lower case.
- Out of these fields, it is mandatory to provide “address_line1”, “country” and either “city” or “zip_code”.
Response Format
The validated address is returned by the API in the form of JSON. Its format is as follows.
{
"results": [
{
"matched_address_line1": "",
"matched_address_line2": "",
"extra_information": "",
"matched_city": "",
"matched_state": "",
"matched_zip_code": "",
"matched_country": "",
"matched_complete_address": "",
"matched_location_type": "",
"matched_status": "",
"matched_status_name": "",
"longitude_coordinates": "",
"latitude_coordinates": "",
"street_number": "",
"street_name": "",
"zip_code": "",
"zip_code_suffix": "",
"input_complete_address": "",
"partial_match": "",
"matched_address_types": []
}
]
}
Let us, dig into each of these fields.
“results” will have a list of matched addresses. Address contains the following fields |
“matched_address_line1” contains the validated data of the street i.e., street number and street name |
“matched_address_line2” contains the validated data of Suite/Apartment/Building. |
“extra_information” contains extra address data, which is usually not part of standard address data, if input address contains any c/o information (phone number, person name etc.). |
“matched_city” contains validated name of the city. |
“matched_state” contains abbreviated name of the validated state or province. |
“matched_zip_code” contains the validated zip code.
|
“matched_country” contains abbreviated name of the validated country. Here, it will still contain abbreviated name even if full name of the country was provided in the input address. And hence, match status in this case will be Standardized. |
“matched_complete_address” contains the complete validated address. It is basically comma separated concatenation of all the above explained matched fields. There is no comma in between “matched_address_line1”, “matched_address_line2” and “matched_state”, “matched_zip_code” |
“matched_location_type” stores additional data about the specified location. The following values are currently supported:
"GEOMETRIC_CENTER"indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
|
“matched_status_name” contains the complete name of the matched status. It can contain one of these values:
|
Each of these statuses is explained next. “matched_status” contains the status of the matched address in abbreviated format. it may contain the following values based on intelligence:
|
|
|
|
|
|
|
|
|
The following types are supported and returned in the matched_address_type arrays:
|
In addition to the above, address components may include the types below.
|
An empty list of types indicates there are no known types for a particular address component, for example, Lieu-dit in France. |
“partial_match” indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address. Partial matches most often occur for street addresses that do not exist within the locality you pass in the request. Partial matches may also be returned when a request matches two or more locations in the same locality |
Response Codes
Following are the response codes that will help user know what kind of response is returned by the API.
Code |
|
Description |
200 |
{ "results": [] } |
It indicates successful processing of request. The results will have a list of matched addresses. |
400 |
{ "message": "Invalid request. Missing the 'addresses' parameter.", "status": 400, "error": "Bad Request" } |
It indicates a parameter is missing from the request body. parameter that will cause this issue is "addresses". |
403 |
{ "message": "API key is missing or invalid in request header.", "status": 403, "error": "Forbidden" } |
It indicates that API key was missing or invalid in the request header. |
406 |
{ "message": "Expected input format is JSON.", "status": 406, "error": "Invalid input format" } |
It indicates the request body format is not correct i.e., backend is expecting json and client is sending request in some other format. |
500 |
{ "message": "Error while processing request.", "status": 500, "error": "Internal server error" } |
It indicates that something went wrong on server. |
504 |
{ "message": "The server didn’t respond in time.", "status": 504, "error": "Timeout" }
|
It indicates that the request did not finish in time and request got timed-out. |
API Request, Response Examples
Example 1
Let see an example where the address data is added separately in address line 1,2 and 3.
Request Body
{
"addresses": [
{
"address_line1": "4000 KRESGE WAY",
"address_line2": "REC DOCK 1",
"address_line3": "TAG 0001238279",
"city": "LOUISVILLE",
"state": "KY",
"zip_code": "40219",
"country": "US",
"company_name": "BAPTIST HEALTH LOUISVILLE"
}
],
"case_format": "",
"zip_code_format": ""
}
Response Body
{
"results": [
{
"matched_city": "Louisville",
"matched_status": "ER",
"extra_information": "REC DOCK 1, TAG 0001238279",
"matched_location_type": "ROOFTOP",
"input_complete_address": "4000 KRESGE WAY REC DOCK 1 TAG 0001238279, LOUISVILLE, KY 40219, US",
"matched_zip_code": "40207-4605",
"matched_state": "KY",
"matched_status_name": "Enrich",
"street_name": "Kresge Way",
"zip_code": "40207",
"longitude_coordinates": "-85.6395549",
"matched_complete_address": "4000 Kresge Way, Louisville, KY 40207-4605, US",
"matched_address_line2": null,
"zip_code_suffix": "4605",
"partial_match": true,
"matched_country": "US",
"street_number": "4000",
"latitude_coordinates": "38.2375702",
"matched_address_type": [
"street_address"
],
"matched_address_line1": "4000 Kresge Way",
}
]
}
Example 2
Let see an example where the address data is added only in address line 1.
Request Body
{
"addresses": [
{
"address_line1": "4000 KRESGE WAY REC DOCK 1 TAG 0001238279",
"city": "LOUISVILLE",
"state": "KY",
"zip_code": "40219",
"country": "US",
"company_name": "BAPTIST HEALTH LOUISVILLE"
}
],
"case_format": "",
"zip_code_format": ""
}
Response Body
{
"results": [
{
"matched_city": "Louisville",
"matched_status": "ER",
"extra_information": "REC DOCK 1, TAG 0001238279",
"matched_location_type": "ROOFTOP",
"input_complete_address": "4000 KRESGE WAY REC DOCK 1 TAG 0001238279, LOUISVILLE, KY 40219, US",
"matched_zip_code": "40207-4605",
"matched_state": "KY",
"matched_status_name": "Enrich",
"street_name": "Kresge Way",
"zip_code": "40207",
"longitude_coordinates": "-85.6395549",
"matched_complete_address": "4000 Kresge Way, Louisville, KY 40207-4605, US",
"matched_address_line2": null,
"zip_code_suffix": "4605",
"partial_match": true,
"matched_country": "US",
"street_number": "4000",
"latitude_coordinates": "38.2375702",
"matched_address_type": [
"street_address"
],
"matched_address_line1": "4000 Kresge Way",
}
]
}
Here, we can see that even if data was only added in address line 1, we were still able to get the expected validated address from the API and non-address related information is added in “extra-information” property.
API Versioning
1) All new changes to API will be published as new API Version. API consumer will be able to use both i.e. latest and previous versions of Address validation API using same API key. Currently only one version is available i.e. https://apis.dvsum.com/address-validation
2) API consumer will have existing and new versions available for testing on Prod environment
3) Every new version will be published with version number in URI i.e
Address Validation Rule
This is a link to Address Validation rules article.
0 Comments