Business Connect API

Hi everyone! Today I will be explaining Huawei’s Business Connect portal and its data APIs to you. First of all, let me introduce you to Business Connect.

Business Connect (BC for short) helps you manage all kinds of businesses after you sign up using a HUAWEI ID, regardless of whether you are a merchant or partner. It brings you multi-channel online traffic based on Huawei’s service advantages and helps you make informed operations decisions through impression data feedback.

The impression advantages of Business Connect are dependent on Huawei’s large user base and extensive mobile ecosystem services. The information you configured in BC can be automatically synchronized to Huawei’s services such as Petal Search and Petal Maps so that users of these services can be converted into potential customers for your business.

Now that we know what Business Connect is and what it can provide us, let’s dive into the capabilities made available to us by BC.

Business Connect API has:

• Authentication API
• Data API

While Authentication API is a standalone API itself, Data API divides into two as Location API and Content API. As the names tell, Authentication API is used for obtaining the token which is required in the Data API. So Authentication API is a prerequisite for the Data API methods.

API Call Process

So let’s get into the technical details of Authentication API first. Initially, you must register as an enterprise developer on HUAWEI Developers. I am linking detailed documentation about how to register your account in order to use the API, so if you haven’t registered already, you can click here to access the guideline to join HUAWEI Developers. Moving forward, now I assume you have already completed the registration part, we can talk about the details.

First of all, you must be logged into the HUAWEI Developers Console. In the left panel, select Credentials under HMS API Services, and select an existing project or create a project.

Afterwards, you must apply for an OAuth 2.0 client ID. If you have already applied before, you can find it under Create Credential tab.

After selecting OAuth 2.0 client ID, you should continue with the option Server App. Now that you filled in all the required information, select Create and you will be presented with your client ID and your key. This is the credentials information we need as we will be using this afterwards to obtain the authentication API token, so save it.

Once we have our credentials, we are ready to obtain our token. We will use getToken method with POST request to achieve this.

Our URL is: https://login.cloud.huawei.com/oauth2/v2/token

Request method is: POST

While sending the request, we need to apply our parameters as Body parameters. Required parameters are:

• grant_type: This is our authorization type. The value should be client_credentials. Input type is String.
• client_id: This is the client ID we obtained shortly before. Input type is Int.
• client_secret: This is the key. Input type is String.

If there is no problems with our parameters, the response structure should contain:

• access_token: After all this hard work, we finally achieve our access token. Response value type is String.
• expires_in: This value shows us our validity period of a token, in seconds. For example, the response is 3600, this means our token will be invalidated after 60 minutes. Response value type is Int.
• token_type: This value contains our token type. For example our value will be Bearer. Response value type is String.

And that will be all for Authentication API. We were doing this process to obtain the access token in order to use it on our operations with Data API. Now that we got it, we can progress forward.

Data API is divided into two parts, first one is Location API, second one is Content API. As the names tell, Location API is used for operations about your business’s location. You can add, update or delete locations for your business. For example, you can add your restaurants informations with this API. On the other hand, Content API is used for operations that is included in your business. For example, products, posts, services, etc. So let’s begin with Location.

First of all, I will start with locations.list method. This method was used for getting a list of locations that meet the specified criteria. But, this method is deprecated and will be removed after January 31, 2022. So, on February 1, 2022, services that has been tried to carry through this method, will fail. For this reason, I am not going to give details about locations.list, but instead, I will describe locations.list (v2), which is the replacement for the deprecated version. While getting down to details, it is also important to mention that the locations.list(v2) API uses the POST method rather than GET and transfers parameters through the request body rather than the URL.

Our URL is: /openapi/biz/account/{organizationId}/locations/v2

Request method is: POST

In the URL parameters, we need to provide our organizationId.

• organizationId: Mandatory. String type. Unique ID of a partner. For example: 123456

In the header of our request, we need to fill in these fields:

• Accept: Mandatory. The value is application/json.
• Content-Type: Mandatory. The value is application/json.
• Authorization: Mandatory. Token we obtained using the getToken API, which should be the Bearer type. The value format must follow as Bearer+Space+token. For example: Bearer CgB6e3x9w7X1ZNlyZkzFDwF63gO

In the body of our request, we can add the fields down below to narrow down our query results.

• name: String type. Name of the location. Example: Pet Store
• idType: Int type. Type of a location ID. Options are, 0 (default value): location ID of a partner, 1: location ID of a merchant.
• locationId: String type. When idType is set to 0, the value of locationId is the value of partnerID. When idType is set to 1, the value of locationId is the value of petalLocationId. Example: s222347
• addressCountry: String type. Country to which the location belongs. Example: US
• addressLocality: String type. City to which the location belongs. Example: Denver
• addressRegion: String type. Region to which the location belongs. Example: CO
• streetAddress: String type. Address of the street to which the location belongs. Example: 20341 Whitworth Institute 405 N. Whitworth
• postalCode: String type. Postal code of the district to which the location belongs. Example: 98052
• primaryTelephone: String type. Primary phone number of the location. Example: 23456678
• latitude: Float type. Latitude of the district to which the location belongs. The value ranges from –90.0 to +90.0. Example: 15.33333
• longitude: Float type. Longitude of the district to which the location belongs. The value ranges from –180.0 to +180.0. Example: 12.33333
• radius: Float type. This parameter must be used together with latitude and longitude. The radius specified by this parameter and the center specified by latitude and longitude form a circle in which businesses meeting the specified criteria will be listed. The unit is meter. This field is reserved. Example: 1000.0
• pageSize: Int type. If the number of records that meet the search criteria is too large, they will be returned on different pages. This parameter specifies the number of records on each page. The default value is 10 and the maximum value is 100. Example: 10
• pageNumber: Int type. Page number of returned data. The default value is 1. If the value of this parameter exceeds the maximum number of pages, the data of the last page will be returned. Example: 1

These fields are used for filtering our results based on the field we provide. As response, we will see a list of locations that meet the specified criteria. Response structure, if no error occurs in the request, should be like down:

• totalSize: Mandatory, Int type. Number of locations that meet the search criteria. For example: 100
• pageSize: Int type. If the number of records that meet the search criteria is too large, they will be returned on different pages. This parameter specifies the number of records on each page. The default value is 10 and the maximum value is 100. For example: 10
• pageNumber: Int type. Page number of returned data. The default value is 1. If the value of this parameter exceeds the maximum number of pages, the data of the last page will be returned. For example: 1
• locations: Mandatory, a list containing Location object type.

Let’s move next to the locations.get method. This method is used for obtaining information about a specific location.

Our URL: /openapi/biz/account/{organizationId}/locations/{petalLocationId}/v1

Request method is: GET

We should provide two mandatory fields in path. These two fields are:

• organizationId: Mandatory. String type. Your unique ID. Example: 123456
• petalLocationId: Mandatory. String type. ID of a location defined in BC. Example: 9527

After the path variables, we should also prepare our header variables. These are the same with locations.list (v2) method. And that’s it for the locations.get request. We do not have any body variables. Response, if request is successful, should return the location instance carrying the petalLocationId field.

Our next method is locations.create. This is the method we use for creating a location. For this method, we will use POST method.

Our URL is: /openapi/biz/account/{organizationId}/locations/v1

Request method: POST

We need to provide organizationId in the path.

• organizationId: Mandatory. String type. Your unique ID. Example: 123456

We also need to provide same header values as previously.

For the body part, we need to prepare a Location instance with blank petalLocationId. Because, if the request is susccessful, this ID will be filled in the system and it will be returned with the data in the response.

Let’s continue with locations.update. We will use this method to update our location informations. For this method, we will use PUT method.

Our URL is: /openapi/biz/account/{organizationId}/locations/{petalLocationId}/v1

Request method: PUT

This method also uses two mandatory fields in path. These two fields are:

• organizationId: Mandatory. String type. Your unique ID. Example: 123456
• petalLocationId: Mandatory. String type. ID of a location defined in BC. Example: 9527

And same header values apply as previously as well.

For the body part, we need to prepare a Location instance with the fields we want to update. Because only the fields carried in requests are updated. If the update is successful, a 200 OK message will be returned; otherwise, an error code will be returned.

And finally, our last method for Location API, locations.delete. As you can tell, we use this method to delete a location. We will use DELETE method.

Our URL is: /openapi/biz/account/{organizationId}/locations/{petalLocationId}/v1

Request Method: DELETE

And again, we need to apply two mandatory parameters to the requests.

• organizationId: Mandatory. String type. Your unique ID. Example: 123456
• petalLocationId: Mandatory. String type. ID of a location defined in BC. Example: 9527

And same header values applies as previously as well.

There is no body for this method, the location with the petalLocationId we provided in the path, gets deleted. If the deletion is successful, a 200 OK message is returned; otherwise, an error code is returned.

This concludes Location API methods, now we can see the details of Content API. This API methods are used to transfer, synchronize, and manage data about partners’ products, services, posts, reviews, and replies in BC. Let’s not waste any time and begin with content.list. This method returns the content that meets the specified criteria.

Our URL is: /openapi/biz/location/content/batch/query/v1

Request Method: POST

Our header values are still the same with locations. And for the body part, these values can be applied:

• organizationId: Mandatory. String type. Unique ID of a partner. In the joint commissioning phase, click Contact Us at the bottom of the website page to request an ID from the BC project team. Example: 123456
• locationId: Mandatory. String type. Location ID of a partner. Example: s222347
• idType: Mandatory. Int type. Type of a location ID. The options are 0 (default value): location ID of a partner, 1: location ID of a merchant. Example: 0
• type: Mandatory. Int type. Content type. The options are as follows, 1: Post, 2: Product, 3: Service, 4: Review. Example: 1
• name: String type. Content name, which is used for exact match. Example: Pet Store
• pageSize: Int type. If the number of records that meet the search criteria is too large, they will be returned on different pages. This parameter specifies the number of records on each page. The default value is 10 and the maximum value is 100. Example: 10
• pageNumber: Int type. Page number of returned data. The default value is 1. If the value of this parameter exceeds the maximum number of pages, the data of the last page will be returned. Example: 1

As for the results, a list of contents that meet the search criteria is returned. The response structure as follows:

• totalSize: Mandatory. Int type. Number of locations that meet the search criteria.
• pageSize: Int type. If the number of records that meet the search criteria is too large, they will be returned on different pages. This parameter specifies the number of records on each page. The default value is 10 and the maximum value is 100. Example: 10
• pageNumber: Int type. Page number of returned data. The default value is 1. If the value of this parameter exceeds the maximum number of pages, the data of the last page will be returned. Example: 1
• posts: List containing Post object. This parameter is available only when type is set to 1.
• products: List containing Product object. This parameter is available only when type is set to 2.
• services: List containing Service object. This parameter is available only when type is set to 3.
• reviews: List containing Review object. This parameter is available only when type is set to 4.

For the object structure of this response and it’s parameters, you can access this link.

Our second method is content.query. This method is used for obtaining a content that meets the specified criteria. We need to use POST method for this one.

Our URL is: /openapi/biz/location/content/query/v1

Request method: POST

Same header structure follows for this one as well. For the body, we need to provide these parameters:

• organizationId: Mandatory. String type. Unique ID of a partner. In the joint commissioning phase, click Contact Us at the bottom of the website page to request an ID from the BC project team. Example: 123456
• locationId: Mandatory. String type. Location ID of a partner.
• contentId: Mandatory. String type. Content ID.
• idType: Mandatory. Int type. Type of a location ID. The options are 0 (default value): location ID of a partner, 1: location ID of a merchant. Example: 0
• type: Mandatory. Int type. Content type. The options are 1: Post, 2: Product, 3: Service, 4: Review.

In the response, if there is no error, we should see a list of posts that meet the search criteria is returned.

Our third method is content.create/update. We use this method to create content.

Our URL is: /openapi/biz/location/content/batch/add/v1

Request method: POST

As always, same header structure is also needed for this method as well.

For the body, same structure with content.list applies.

For the response, if there is no error, we should see a list of created or updated objects.

Finally, the last method of this guide, content.delete. This method deletes the specified content.

Our URL is: /openapi/biz/location/content/batch/delete/v1

Request method: POST

For the body part, we need these parameters:

• organizationId: Mandatory. String type. Unique ID of a partner. In the joint commissioning phase, click Contact Us at the bottom of the website page to request an ID from the BC project team. Example: 123456
• locationId: Mandatory. String type. Location ID of a partner. Example: s222347
• idType: Mandatory. Int type. Type of a location ID. The options are 0 (default value): location ID of a partner, 1: location ID of a merchant. Example: 0
• type: Mandatory. Int type. Content type. The options are as follows: 1: Post, 2: Product, 3: Service, 4: Review.
• ids: List of String. List of BC-side IDs of deleted content. Example: [123,235,223]
• source_ids: List of String. List of partner-side IDs of deleted content. Example: [p333,p335,p233]

If the deletion is successful, a 200 OK message is returned; otherwise, an error code is returned.

In conclusion…

That’s all for our API methods. We have finally reviewed all of the methods of Authentication API and Data API. We have iterated over steps of every method in the APIs. Now, we are able to achieve successful implementations for Business Connect.

References

Overview | Business Connect

Get Your Business Listed on Huawei Ecosystem with Business Connect Portal