APIs Related to Geographic Locations

Last Updated on : 2025-05-30 01:56:03download

API List

Request method	API	Description
GET	/v1.0/osaas/locations	API for Obtaining the Geographic Location List
GET	/v1.0/osaas/locations/{location_id}	API for Obtaining Geographic Location Details

API for Obtaining the Geographic Location List

API Description

You can use this API to obtain the geographic location list of the lower level.

API Address

GET /v1.0/osaas/locations

Request Parameters

Parameter	Type	Position	Description	Mandatory
parent_location_id	String	URL	Unique ID of the parent geographic location. 0: China -1: international	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Array	Geographic location set.

Parameters in result

Parameter	Type	Description
location_id	String	Unique ID of a geographic location.
name	String	Name of a geographic location
parent_location_id	String	Unique ID of the parent geographic location
level	Integer	Level of a geographic location.

Request Example

GET {url}/v1.0/osaas/locations?parent_location_id=-1

Success Response Example

{
  "result": [
    {
      "location_id": "0",
      "level": 0,
      "name": "China",
      "parent_location_id": "-1"
    }
  ],
  "success": true,
  "t": 1586229786371
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Geographic Location Details

API Description

You can use this API to obtain geographic location details based on the unique ID of a geographic location.

API Address

GET /v1.0/osaas/locations/{location_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
location_id	String	URI	Unique ID of a geographic location.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Details about a geographic location.

Parameters in result

Parameter	Type	Description
location_id	String	Unique ID of a geographic location.
name	String	Name of a geographic location
parent_location_id	String	Unique ID of the parent geographic location
level	Integer	Level of a geographic location.

Request Example

GET {url}/v1.0/osaas/locations/11

Success Response Example

{
  "success": true,
  "t": 1566053034624,
  "result": {
    "location_id": "0",
    "level": 0,
    "name": "China",
    "parent_location_id": "-1"
  }
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error