Using Huawei Site Kit Web API on Flutter
Learn how to build a Flutter application using Huawei Site Kit Web API.
Introduction
Application Programming Interfaces (API) are powerful tools that allow the capabilities of one computer program to be used by another. You can benefit from pre-trained machine learning models, query different kinds of databases, and more… In this article I am going to show how you can use Web API’s and communicate with another server, store the values taken from them on Flutter. We are going to send requests to Huawei Site Kit’s Web API and use the response in our application.
Huawei Site Kit Web API
Huawei Site Kit is a development kit for Android applications that provides location search functions like auto-completing keywords, searching for places and providing the details of places. With integrating this kit into your application, you can search for a destination with keywords including location types like restaurants, hotels, hospitals and 500+ more and provide detailed information including rating, address and phone number of the place.
You can benefit from Huawei Site Kit’s database by sending queries to its Web API. More than 130 million locations and its detailed information are accessible with easy to use API. All of these services and more is also supported in 13 languages and 200+ countries.
Required Configurations
Taking API key
Before using the route planning function, you need to obtain the API key in AppGallery Connect. To enhance the API key security, you are advised to enable restrictions on the API key. This can be done by setting Application Restrictions or API Restrictions. You can obtain the API key in either of the following ways:
- Obtain the API key from the HUAWEI Developers. For details, please refer to API Console Operation Guide.
- Obtain the API key automatically generated when you create an app in AppGallery Connect.
- Sign in to AppGallery Connect and click My projects.
- Find your app project, and click the app name.
- Go to Project Setting > General information. In the App information area, click the ‘copy’ icon next to API key. The API key will then be copied to the clipboard.
Required Plugins and Packages
1- http plugin: This package helps us to send HTTP request to web API.
Add the plugin as a dependency to your project’s pubspec.yaml file and run flutter pub get command to integrate http plugin to your project.
2- convert package: This built-in package is converting JSON string into map for dart applications.
Importing these built-in package is enough to use them.
Huawei Site Kit Web API in Demo Application
Introduction
We are going to build a simple application to show how you can use the Huawei Site Kit Web API in Flutter. Our application in going to take a coordinate from the user, and then query the Web API to check for certain places: Restaurants, Hotels and Hospitals in a certain range from the user’s coordinates.
Classes and Parsing
We are going to send request to Huawei’s servers and get some response. When we are communicating with servers we mostly use JSON strings. And Huawei servers are not exceptions. So we need to create our Response and Request classes considering JSON data structure. In this demo application we are going to use ‘Nearby Place Search’ model of the API. So you can check out the details of the request model we are going to use and other models from the link below:
Servers are expecting JSON string as request. We are going to use convert package to create JSON string from request object. Converting to JSON string is done by maps. So we also need to create String to dynamic map from our request object to use convert package. All optional and mandatory parts with the conversion to map method (toJson) are implemented below.
After sending the request, servers are going to respond with JSON string. We need to decode it using ‘convert’ package. Decoding is going to convert it to a map. We will be creating our Response object using that map. fromJson method is doing that task.
We now have our Site list as a result of the API call. To convert the Response JSON into a class instance, we also need to have a method to create a Site object from the JSON string. The other classes we need to form a Site object are also implemented in a similar manner. So I am only going to share Site class. Other classes are also in the repository.
For more information about parsing complex JSON files, you can check out the link below.
Sending API Calls and Taking Response
Before sending our request, we need to take the request parameters from the user. We only chose three of the location categories which are hotels, restaurants and hospitals. Other parameters we are going to use are coordinate and the distance from that coordinate. We used Slider widget to take the distance from the coordinates, and TextField widgets for coordinates. In the example below, some street in San Francisco is chosen and searched for restaurants within 10.000 meters.
You can increase the location type options or you can prefer to take this parameter completely from the user as a text. Some more meaningful options can be used for radius too, like selecting ‘five minutes by walk’ or ’15 minutes by car’ etc. And finally taking the user’s current location using Huawei Location Kit may be a better practice than taking the input from user.
Now we can create our request, and send it as a POST request using the ‘http’ plugin. Built-in ‘convert’ package is used for converting the JSON string into dart map and vice versa. SendSearchRequest function is invoked when we click ‘Search’ button.
After creating the request with the parameters we take from user, we need to send the request to the servers. URL given with the string literal is the URL of Huawei Map Kit servers. You can also change the ‘nearbySearch’ part of the URL for other functions. For example: ‘searchByText’ for Keyword Search request and ‘searchById’ for Place Detail Search request. Don’t forget to check the request parameters for different query types. You can check them from the document given in the Classes and Parsing section above. Lastly, you need to add the API key you take with your Huawei developer account. If the API key contains special characters, you need to encode it using encodeURI. For example, if the original API key is ABC/DFG+, the conversion result is ABC%2FDFG%2B.
‘Headers’ parameter of the http POST request tells the server what type of data we are sending. ‘application/json’ is used for JSON string. Body part is our request, it is first converted to a map with our toJson method and then converted to JSON string with convert package’s encode function.
http.post function returns http.Response object, which has two fields. First one is statusCode that indicates if the response is successfully received. You can use conditionals to check it and take some action respectively. Second field of http.Response object is ‘body’ which is sent by the server. So we take that body field of the http.Response and decode it to a map using convert package’s decode function. Then by using fromJSON method we implemented, we convert it to Response object.
We now have the response object with the list of relevant sites within given radius. We also sorted the list with respect to their distance from the target. You can change that sorting to ‘rating’ or something else. Each site’s name, address and phone number is displayed in a custom Card widget.
Github Repository
Parsing of complex JSON string into dart classes and UI elements of the application can be seen on Github repository. If you want to see the codes not mentioned in this article you can check out the Github link of the demo application.
Conclusion
As you can see, it is so simple to use Web API’s with Flutter. This application is just using three of the request parameters. You can use others too and build much more comprehensive applications. You can also combine your application with the Huawei Map Kit and build an application using both a multi-functional map and database of more than 130 million destinations all around the world.
