Address Parser

Endpoint Overview

POST /api/v1/ai/parse-address

Description

The Address Parser API extracts structured address components from unstructured address text. It intelligently identifies and categorizes address elements such as street, locality, city, state, and pincode from free-form address strings. This service helps standardize address data across your applications, improving data quality and enabling more accurate address management.

Key Benefits

Converts unstructured address text into standardized, structured data

Improves address data quality for better geocoding and mapping

Reduces manual data entry errors and processing time

Enables consistent address formatting across your applications

Use Cases

E-commerce

Real Estate

Financial Services

Validate and standardize shipping addresses during checkout

Improve delivery accuracy by extracting precise address components

Reduce failed deliveries due to address formatting issues

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication (format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
address	String	Yes	The unstructured address text to be parsed

Example Request

{
    "address": "A 403 Ramnagariya Jagatpura Jaipur 302017 Rajasthan"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the parsed address components
data.client_id	String	Unique identifier for the client
data.street	String	Extracted street address
data.locality	String	Extracted local area or neighborhood
data.city	String	Extracted city name
data.state	String	Extracted state name
data.pincode	String	Extracted postal code
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "address_parser_LoJsfhksdbwwreoUsaQb",
        "street": "A Ramnagariya",
        "locality": "Jagatpura",
        "city": "Jaipur",
        "state": "Rajasthan",
        "pincode": "302017"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Input

Parsing Error

{
    "status_code": 401,
    "success": false,
    "message": "Invalid authentication token",
    "message_code": "authentication_error"
}

This error occurs when the JWT token is missing, expired, or invalid.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption

Implement proper error handling for authentication failures

User Experience Guidelines

Provide clear feedback to users when address parsing fails

Consider implementing address validation before submission

Allow users to review and correct parsed address components

Cache parsed results to improve performance for repeated addresses

Code Samples

cURL

Python

Node.js

Related APIs

OCR Document API: Extract text from document images for address parsing

Address Verification API: Verify the existence and deliverability of parsed addresses

Geocoding API: Convert parsed addresses into geographic coordinates

Compliance and Legal Considerations

When processing address data, be aware of data protection regulations such as GDPR, CCPA, or local data privacy laws. Address information is considered personal data and should be handled accordingly. Ensure you have proper consent for processing address data and implement appropriate data retention policies.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ai/parse-address' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "address": "A 403 Ramnagariya Jagatpura Jaipur 302017 Rajasthan" }'

{ "data": { "client_id": "address_parser_LoJsfhksdbwwreoUsaQb", "street": "A Ramnagariya", "locality": "Jagatpura", "city": "Jaipur", "state": "Rajasthan", "pincode": "302017" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Address Parser

Address Parser#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Address Parser

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples