CountryLocation API Documentation

Base URL: https://api.countrylocation.com/

Overview

This API provides endpoints for user authentication and postal code management. Below are the details of the available endpoints.

Authentication Endpoints

1. Register

POST /api/register

Registers a new user.

Request Body:
{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "password": "password123",
    "password_confirmation": "password123"
}
Example Response:
{
    "status": "success",
    "message": "User registered successfully.",
    "token": "your-access-token"
}

2. Login

POST /api/login

Logs in an existing user.

Request Body:
{
    "email": "john.doe@example.com",
    "password": "password123"
}
Example Response:
{
    "status": "success",
    "message": "Login successful.",
    "token": "your-access-token"
}

3. Forgot Password

POST /api/forgot-password

Sends a password reset link to the user’s email.

Request Body:
{
    "email": "john.doe@example.com"
}
Example Response:
{
    "status": "success",
    "message": "Password reset link sent to your email."
}

4. Reset Password

POST /api/reset-password

Resets the user's password using a valid token.

Request Body:
{
    "email": "john.doe@example.com",
    "token": "reset-token",
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
}
Example Response:
{
    "status": "success",
    "message": "Password has been reset."
}

Postal Codes Endpoints

1. Retrieve All Postal Codes

GET /api/postal-codes

Retrieves a list of postal codes with optional filters.

Query Parameters:
  • postal_code (string) - Filter by postal code.
  • country_code (string) - Filter by country code.
  • admin_name1 (string) - Filter by administrative region.
Example Request:
GET /api/postal-codes?country_code=IN
Example Response:
{
    "status": "success",
    "data": [
        {
            "postal_code": "421605",
            "country_code": "IN",
            "place_name": "Phalegaon"
        }
    ]
}

2. Retrieve Postal Code Details

GET /api/postal-codes/{postalCode}

Gets detailed information about a specific postal code.

Example Request:
GET /api/postal-codes/421605
Example Response:
{
    "status": "success",
    "data": {
        "postal_code": "421605",
        "country_code": "IN",
        "place_name": "Phalegaon",
        "admin_name1": "Maharashtra"
    }
}

3. Find Nearby Locations

GET /api/postal-codes/nearby/area

Finds postal codes near a specific latitude and longitude.

Query Parameters:
  • latitude (numeric) - Latitude of the location.
  • longitude (numeric) - Longitude of the location.
  • radius (numeric, optional) - Search radius in kilometers (default: 10).
Example Request:
GET /api/postal-codes/nearby/area?latitude=19.36&longitude=73.32&radius=15
Example Response:
{
    "status": "success",
    "data": [
        {
            "postal_code": "421604",
            "country_code": "IN",
            "place_name": "Nearby Place"
        }
    ]
}