POI's Sub Category

The KSA Service Sub Category API returns list of services which fall under a service category in KSA region along with service id and name. Using the service sub-category API you can tag business in a district, city or region to provide structured information to your users. You can decide to use Json or XML as an output format in addition to language of your choice from Arabic or English.

Usage:

You must use an access token to make an authenticated call to our system. Access token are generated based on your subscription type. To get your access token please refer to “Your Subscriptions” section available on profile page.

Limits for calls to API

Our system doesn’t apply any limits on number of requests you can make for a particular API. But there are limits defined for total number of calls you can make per min and in one week. Please reference the list below for limits applied

• Starter Package - Subscribers will be able to execute 5 calls/ minute up to a maximum of 100 calls/ week for any API.

• Unlimited Package - Subscribers can make as many calls as they wish per minute or in a week with no upper limit defined. This package will have to be approved by our system administrator and make time.

API Request
Input Parameters

Field

    Description

Format(optional)

    It’s an optional input. We currently support output for API’s in two formats Json and XML. You will be required to specify in which format you need response, default is Json

Language

    It’s an optional input. Our API’s can provide response in Arabic or English with Arabic being the default language.

api_key

    Access token to authenticate you as a valid user of the system. Please refer to profile section to get your subscription key.

ServiceCategoryID

    ID of service category by which its recognized in system. You can obtain service category id by using Service Category API.

encode

    By default response is in windows-1256.

    Support for utf-8 is added as of now. Pass "utf8" as input parameter.

Requested URL

https://apina.address.gov.sa/NationalAddress/v3.1/lookup/services-sub-categories?language=A&format=JSON&servicecategoryid=1&api_key=

Response

Default Fields Returned

By default, only the following fields are returned for a profile request:

Field

    Description

ID

    ID of service sub category by which it’s recognized in the system.

Name

    Name of Service as in national address register.

Success

    This represents success or failure of the request itself (true/false).

Status Description

    This provides a description of the current status, validation messages or error messages, if any.

Sample Response
JSON

{"LookUp": null, "Regions": null, "Cities": null, "Districts": null, "ServiceCategories": null, "ServiceSubCategories":[{"Id": "1C", "Name": "Civil Defense"}, {"Id": "1F", "Name": "General Government Services"}, {"Id": "1A", "Name": "Ministries"}, {"Id": "1B", "Name": "Police Stations"}, {"Id": "1D", "Name": "Postal Services"}, ], "success": true, "datasetOrdatatable": null, "result": null, "statusdescription": "SUCCESS", "fullexception": null}

XML

<LookupOutputParams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <success>true</success> <statusdescription>SUCCESS</statusdescription> <ServiceSubCategories> <ServiceSubCategory> <Id>1C</Id> <Name>Civil Defense</Name> </ServiceSubCategory> </ServiceSubCategories> </LookupOutputParams>

Common Errors

If there's an error with your API call, LinkedIn will return a HTTP status code along with a message detailing the error

 CodeDescription                                                                      Solution

 400 Bad Request                                                                       The request was invalid, which is usually caused by a programming error. Ensure that the request is                                                                                                                               formatted correctly.                                                                                                                                                                 401 "Access denied due to invalid subscription key.          Ensure that a valid access token is being used in your API call By catching 401 unauthorized exceptions                              Make sure you are subscribed to an API you are       in all your calls you'll provide the coverage you need in your application to handle expired tokens. It's good                      trying to call and provide the right key."                      practice to design and develop your application in anticipation that with any request you could potentially                                                                                                                    have an invalid access token. 

 403 Total limit for calls for your subscription has               You've reached the total limit of calls for web services. Based on your subscription type you have a defined                     been reached.                                                                   number of calls which can be made. Please refer to “Products” section to know more about your                                                                                                                                      subscription.                                                                                                                                                                               404 Page not found                                                                  The endpoint or resource your application is trying to reach doesn't exist.                                                                   500 Internal Service Error                                                        There was an application error on our server. Usually your request is valid but needs to be made at a later time.