API - Location

Created by KloudShip Support, Modified on Fri, 24 Oct at 7:48 PM by KloudShip Support

GET: Get location

The Get Location API provides information about different locations, including warehouses and offices. This API allows you to retrieve details such as the address, contact information, and geolocation coordinates for each location. Below is the documentation for the Get Location API.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Location?pageNumber=1&fromDate=&toDate=&searchString=&newestFirst=false
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Location?pageNumber=1&fromDate=&toDate=&searchString=&newestFirst=false
Content-Type	application/json

Query parameter:

Parameter	Type	Required	Description	Example
`pageNumber`	integer	No	Page number for pagination. Default is `1`.	`1`
`fromDate`	string (ISO)	No	Filter locations created after this date.	`2025-01-01T00:00:00Z`
`toDate`	string (ISO)	No	Filter locations created before this date.	`2025-02-01T00:00:00Z`
`searchString`	string	No	Keyword to search by name or address.	`Noida`
`newestFirst`	boolean	No	If `true`, results are sorted by newest first. Default is `false`.	`true`

Request body:

Does not require any request parameter

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Location?pageNumber=1&fromDate=&toDate=&searchString=&newestFirst=false' \
--header 'Authorization: Bearer <your_token>' \
--data ''

Response fields:

Root Level

Field	Type	Description
`results`	`array`	List of location objects.
`pageSize`	`integer`	Number of records returned per page.
`totalResults`	`integer`	Total number of matching locations.
`totalPages`	`integer`	Total pages available.
`currentPage`	`integer`	Current page index.

Address Object (`results[].address`)

Field	Type	Description
`verificationStatus`	`string`	Verification result (e.g., `"Success"`, `"Failed"`, `"Pending"`).
`firstName`	`string`	Contact first name for the location.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name (may be empty).
`street1`	`string`	Primary street address line.
`street2`	`string`	Secondary street address line (may be empty).
`street3`	`string`	Tertiary street address line (may be empty).
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., `"UP"`, `"MH"`).
`zip`	`string`	Postal / PIN code.
`countryCode`	`string`	Country code (ISO, e.g., `"IN"`).
`phone`	`string`	Primary phone number.
`phoneCode`	`string`	Country calling code (e.g., `"+91"`).
`verify`	`boolean`	Whether the address has been verified (request-level flag).
`category`	`string`	Address category (e.g., `"Commercial"`, `"Residential"`).
`email`	`string`	Contact email for the location.
`latitude`	`number`	Latitude coordinate (decimal).
`longitude`	`number`	Longitude coordinate (decimal).
`landmark`	`string (optional)`	Nearby landmark (if any).
`addressId`	`string (optional)`	Internal ID of the address entity (if returned).

Response example:

{
    "results": [
        {
            "id": "6784fed7326a0ee24be9f4f7",
            "name": "Impledge Location",
            "createdDate": "2025-01-13T11:53:59.277Z",
            "isDefault": false,
            "defaultUsersCount": 0,
            "type": "Warehouse",
            "address": {
                "verificationStatus": "Success",
                "firstName": "Guest",
                "lastName": "User",
                "company": "",
                "street1": "Regus, 5th Floor, TOWER-C, Green Boulevard, Rasoolpur Nawada, B-Block, Sector 62,",
                "city": "Noida",
                "stateCode": "UP",
                "zip": "201309",
                "countryCode": "IN",
                "phone": "9999999999",
                "phoneCode": "+91",
                "verify": false,
                "category": "Commercial",
                "email": "guest@kloudship.com",
                "latitude": 28.6223216,
                "longitude": 77.3660891
            }
        },
        {
            "id": "678a3ea9c17c95b6756b00e5",
            "name": "KloudShip Guest XpressBees",
            "createdDate": "2025-01-17T11:27:37.699Z",
            "isDefault": false,
            "defaultUsersCount": 0,
            "type": "Warehouse",
            "address": {
                "verificationStatus": "Success",
                "firstName": "Guest",
                "lastName": "User XpressBees",
                "company": "Guest company",
                "street1": "Post Office G.N. BAZAR",
                "city": "Mathurea",
                "stateCode": "UP",
                "zip": "281121",
                "countryCode": "IN",
                "phone": "9999999996",
                "phoneCode": "+91",
                "verify": false,
                "category": "Commercial",
                "email": "guest@kloudship.com",
                "latitude": 27.5109929,
                "longitude": 77.6778616
            }
        }
    ],
    "pageSize": 20,
    "totalResults": 2,
    "totalPages": 1,
    "currentPage": 1
}

GET: Location by ID

The Get Location by ID API allows you to retrieve location information based on a unique identifier (ID). This API provides detailed information about a specific location, including its name, type, address, and contact details.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Location/{id}
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Location/{id}
Content-Type	application/json

{id}: Here you will provide the location id

Request body:

Does not require any request parameter

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Location/6784fed7326a0ee24be9f4f7' \
--header 'Authorization: ••••••' \
--data ''

Response fields:

Root Level

Field	Type	Description
`id`	`string`	Unique identifier for the location.
`name`	`string`	Display name of the location.
`createdDate`	`string (ISO 8601)`	Created timestamp (e.g., `"2025-10-15T12:46:11.153Z"`).
`isDefault`	`boolean`	Whether this location is the default one.
`defaultUsersCount`	`integer`	Count of default users assigned to this location.
`type`	`string`	Type of location (e.g., `"Warehouse"`, `"Hub"`, `"Store"`).
`address`	`object`	Address object containing detailed address information (see below).

Address Object (`address`)

Field	Type	Description
`verificationStatus`	`string`	Verification result (e.g., `"Success"`, `"Failed"`, `"Pending"`).
`firstName`	`string`	Contact first name for the location.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name (may be empty).
`street1`	`string`	Primary street address line.
`street2`	`string`	Secondary street address line (may be empty).
`street3`	`string`	Tertiary street address line (may be empty).
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., `"UP"`, `"MH"`).
`zip`	`string`	Postal / PIN code.
`countryCode`	`string`	Country code (ISO, e.g., `"IN"`).
`phone`	`string`	Primary phone number.
`phoneCode`	`string`	Country calling code (e.g., `"+91"`).
`verify`	`boolean`	Whether the address has been verified.
`category`	`string`	Address category (e.g., `"Commercial"`, `"Residential"`).
`email`	`string`	Contact email for the location.
`latitude`	`number`	Latitude coordinate (decimal).
`longitude`	`number`	Longitude coordinate (decimal).

Response example:

{
    "id": "6784fed7326a0ee24be9f4f7",
    "name": "Impledge Location",
    "createdDate": "2025-01-13T11:53:59.277Z",
    "isDefault": false,
    "defaultUsersCount": 0,
    "type": "Warehouse",
    "address": {
        "verificationStatus": "Success",
        "firstName": "Guest",
        "lastName": "User",
        "company": "",
        "street1": "Regus, 5th Floor, TOWER-C, Green Boulevard, Rasoolpur Nawada, B-Block, Sector 62,",
        "street2": "",
        "street3": "",
        "city": "Noida",
        "stateCode": "UP",
        "zip": "201309",
        "countryCode": "IN",
        "phone": "9799999999",
        "phoneCode": "+91",
        "verify": false,
        "category": "Commercial",
        "email": "guest@kloudship.com",
        "latitude": 28.6223216,
        "longitude": 77.3660891
    }
}

POST: Create location

The Post Create Location API allows you to create and post address information to our system. This API is designed to handle address details for various types of locations, such as offices, warehouses, and more. This document provides comprehensive information about the request structure, response format, and endpoint details for using the Post Address API.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Location
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Location
Content-Type	application/json

Request body:

The request body should contain a JSON object with the address information to be posted. Here is an example of the

request body:

Field	Type	Required	Description
`name`	`string`	Yes	Display name of the location.
`type`	`string`	Yes	Type of location (e.g., `"Warehouse"`, `"Hub"`, `"Store"`).
`address`	`object`	Yes	Address details object (see below).

Address Object (Request)

Field	Type	Required	Description
`firstname`	`string`	Yes	Contact first name for the location.
`lastname`	`string`	No	Contact last name.
`company`	`string`	No	Company or business name.
`street1`	`string`	Yes	Primary street address line.
`street2`	`string`	No	Secondary street address line (optional).
`street3`	`string`	No	Tertiary street address line (optional).
`city`	`string`	Yes	City name.
`stateCode`	`string`	Yes	State code (e.g., `"DL"`, `"UP"`).
`countryCode`	`string`	No	Country code (ISO format, e.g., `"IN"`).
`phone`	`string`	Yes	Contact phone number.
`zip`	`string`	Yes	Postal / PIN code.
`email`	`string`	Yes	Contact email for the location.
`isResidential`	`boolean`	No	Whether the address is residential (`true`/`false`).
`latitude`	`number`	No	Latitude coordinate (decimal).
`longitude`	`number`	No	Longitude coordinate (decimal).
`verify`	`boolean`	No	Whether to verify the address before saving.

Request example:

{
    "name": "abc",
    "type": "Warehouse",
    "address": {
        "firstname": "xyz",
        "lastname": " ",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi ",
        "stateCode": "DL",
        "countryCode": "IN",
        "phone": "959999999",
        "zip": "110032",
        "email": "viabc@kloudship.com",
        "isResidential": false,
        "latitude": 0.0,
        "longitude": 0.0,
        "verify":true
    }
}

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Location' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
    "name": "abc",
    "type": "Warehouse",
     "address": {
        "firstname": "xyz",
        "lastname": " ",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi ",
        "stateCode": "DL",
        "countryCode": "IN",
        "phone": "959999999",
        "zip": "110032",
        "email": "viabc@kloudship.com",
        "isResidential": false,
        "latitude": 0.0,
        "longitude": 0.0,
        "verify":true
    }
}'

Response fields:

Root Level

Field	Type	Description
`id`	`string`	Unique identifier for the created location.
`name`	`string`	Name of the created location.
`createdDate`	`string (ISO 8601)`	Timestamp when the location was created.
`isDefault`	`boolean`	Whether this is the default location.
`defaultUsersCount`	`integer`	Count of default users assigned to this location.
`type`	`string`	Type of location (e.g., `"Warehouse"`, `"Hub"`, `"Store"`).
`address`	`object`	Address object with verification and contact details (see below).

Address Object (Response)

Field	Type	Description
`verificationStatus`	`string`	Address verification result (e.g., `"Success"`, `"Failed"`, `"Pending"`).
`firstName`	`string`	Contact first name for the location.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name.
`street1`	`string`	Primary street address line.
`street2`	`string`	Secondary street address line (if any).
`street3`	`string`	Tertiary street address line (if any).
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., `"DL"`).
`zip`	`string`	Postal / PIN code.
`countryCode`	`string`	Country code (ISO, e.g., `"IN"`).
`phone`	`string`	Contact phone number.
`phoneCode`	`string`	Country calling code (e.g., `"+91"`).
`verify`	`boolean`	Whether the address was verified.
`category`	`string`	Address category (e.g., `"Commercial"`, `"Residential"`).
`email`	`string`	Contact email.
`latitude`	`number`	Latitude coordinate.
`longitude`	`number`	Longitude coordinate.

Response example:

{
    "id": "68efa2bf340a4de8435bb323",
    "name": "abc",
    "createdDate": "2025-10-15T13:33:52.9642487Z",
    "isDefault": false,
    "defaultUsersCount": 0,
    "type": "Warehouse",
    "address": {
        "verificationStatus": "Success",
        "firstName": "abc",
        "lastName": "",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi",
        "stateCode": "DL",
        "zip": "110032",
        "countryCode": "IN",
        "phone": "95999999",
        "phoneCode": "+91",
        "verify": true,
        "category": "Commercial",
        "email": "abc@kloudship.com",
        "latitude": 0.0,
        "longitude": 0.0
    }
}

PUT: Update Location

Updates the details of the location based on the provided location ID.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Location/{id}
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Location/{id}
Content-Type	application/json

{id}: Here you will provide the location id

Request body:

The request body should contain a JSON object with the address information to be posted. Here is an example of the

request body:

Field	Type	Required	Description
`name`	`string`	Yes	Display name of the location.
`type`	`string`	Yes	Type of location (e.g., `"Warehouse"`, `"Hub"`, `"Store"`).
`address`	`object`	Yes	Address details object (see below).

Address Object (Request)

Field	Type	Required	Description
`firstname`	`string`	Yes	Contact first name for the location.
`lastname`	`string`	No	Contact last name.
`company`	`string`	No	Company or business name.
`street1`	`string`	Yes	Primary street address line.
`street2`	`string`	No	Secondary street address line (optional).
`street3`	`string`	No	Tertiary street address line (optional).
`city`	`string`	Yes	City name.
`stateCode`	`string`	Yes	State code (e.g., `"DL"`, `"UP"`).
`countryCode`	`string`	No	Country code (ISO format, e.g., `"IN"`).
`phone`	`string`	Yes	Contact phone number.
`zip`	`string`	Yes	Postal / PIN code.
`email`	`string`	Yes	Contact email for the location.
`isResidential`	`boolean`	No	Whether the address is residential (`true`/`false`).
`latitude`	`number`	No	Latitude coordinate (decimal).
`longitude`	`number`	No	Longitude coordinate (decimal).
`verify`	`boolean`	No	Whether to verify the address before saving.

Request example:

{
    "name": "abc",
    "type": "Warehouse",
    "address": {
        "firstname": "xyz",
        "lastname": " ",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi ",
        "stateCode": "DL",
        "countryCode": "IN",
        "phone": "959999999",
        "zip": "110032",
        "email": "viabc@kloudship.com",
        "isResidential": false,
        "latitude": 0.0,
        "longitude": 0.0,
        "verify":true
    }
}

Example cURL:

curl --location --request PUT 'https://api-ppd.kloudship.com:960/api/v1/Location/68efa9f1340a4de8435bb331' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
    "name": "abc",
    "type": "Warehouse",
     "address": {
        "firstname": "xyz",
        "lastname": " ",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi ",
        "stateCode": "DL",
        "countryCode": "IN",
        "phone": "959999999",
        "zip": "110032",
        "email": "viabc@kloudship.com",
        "isResidential": false,
        "latitude": 0.0,
        "longitude": 0.0,
        "verify":true
    }
}'

Response fields:

Root Level

Field	Type	Description
`id`	`string`	Unique identifier for the created location.
`name`	`string`	Name of the created location.
`createdDate`	`string (ISO 8601)`	Timestamp when the location was created.
`isDefault`	`boolean`	Whether this is the default location.
`defaultUsersCount`	`integer`	Count of default users assigned to this location.
`type`	`string`	Type of location (e.g., `"Warehouse"`, `"Hub"`, `"Store"`).
`address`	`object`	Address object with verification and contact details (see below).

Address Object (Response)

Field	Type	Description
`verificationStatus`	`string`	Address verification result (e.g., `"Success"`, `"Failed"`, `"Pending"`).
`firstName`	`string`	Contact first name for the location.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name.
`street1`	`string`	Primary street address line.
`street2`	`string`	Secondary street address line (if any).
`street3`	`string`	Tertiary street address line (if any).
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., `"DL"`).
`zip`	`string`	Postal / PIN code.
`countryCode`	`string`	Country code (ISO, e.g., `"IN"`).
`phone`	`string`	Contact phone number.
`phoneCode`	`string`	Country calling code (e.g., `"+91"`).
`verify`	`boolean`	Whether the address was verified.
`category`	`string`	Address category (e.g., `"Commercial"`, `"Residential"`).
`email`	`string`	Contact email.
`latitude`	`number`	Latitude coordinate.
`longitude`	`number`	Longitude coordinate.

Response example:

{
    "id": "68efa2bf340a4de8435bb323",
    "name": "abc",
    "createdDate": "2025-10-15T13:33:52.9642487Z",
    "isDefault": false,
    "defaultUsersCount": 0,
    "type": "Warehouse",
    "address": {
        "verificationStatus": "Success",
        "firstName": "abc",
        "lastName": "",
        "company": "Impledge company",
        "street1": "Regus 5th floor",
        "street2": "",
        "street3": "",
        "city": "Delhi",
        "stateCode": "DL",
        "zip": "110032",
        "countryCode": "IN",
        "phone": "95999999",
        "phoneCode": "+91",
        "verify": true,
        "category": "Commercial",
        "email": "abc@kloudship.com",
        "latitude": 0.0,
        "longitude": 0.0
    }
}

DEL: Delete location

The Delete Location API allows you to delete a specific address location using its unique `location_id`.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Location/{id}
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Location/{id}
Content-Type	application/json

{id}: Here you will provide the location id

Example cURL:

curl --location --request DELETE 'https://api-ppd.kloudship.com:960/api/v1/Location/676aad43e60bb079a418f79a' \
--header 'Authorization: ••••••' \
--data ''

Response:

The response from the Delete Location API includes the status code 200, which signify the request was successful and the server has responded with the requested information. The response will contain either a "true" or "false" value.

Not Yet Signed Up?

Get started with KloudShip - This article explains steps like signing up, KYC, and adding balance to your account

API - Location

GET: Get location

Endpoint details:

Query parameter:

Request body:

Example cURL:

Response fields:

Root Level

Address Object (results[].address)

Response example:

Endpoint details:

Request body:

Example cURL:

Response fields:

Root Level

Address Object (address)

Response example:

Endpoint details:

Request body:

Address Object (Request)

Request example:

Example cURL:

Response fields:

Root Level

Address Object (Response)

Response example:

PUT: Update Location

Endpoint details:

Request body:

Address Object (Request)

Request example:

Example cURL:

Response fields:

Root Level

Address Object (Response)

Response example:

Endpoint details:

Example cURL:

Response:

Address Object (`results[].address`)

Address Object (`address`)