Cities
The KSA Cities API returns a list of cities in KSA region along with city id which can be used in other API’s. 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
RegionId
Default value is -1 which will return all cities in KSA
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/cities?format=JSON®ionid=-1&language=A&api_key=
Response
Default Fields Returned
By default, only the following fields are returned for a profile request:
Field
Description
ID
ID of city by which it’s recognized in the system. This ID can be used as input for other API’s Like City Districts.
Name
Name of the city 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.
GovernorateName
Name of the city
Sample Response
JSON
{ "LookUp": null, "Regions": null, "Cities": [
{"Id":"14","Name":"المدينة المنورة","GovernorateName":"امارة منطقة المدينة المنورة"},{"Id":"483","Name":"ينبع","GovernorateName":"ينبع البحر"},{"Id":"9605","Name":"ينبع الصناعية","GovernorateName":"ينبع البحر"}], "Districts": null, "ServiceCategories": null, "ServiceSubCategories":null, "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> <Cities> <City><Id>14</Id><Name>المدينة المنورة</Name><GovernorateName>امارة منطقة المدينة المنورة</GovernorateName></City><City><Id>483</Id><Name>ينبع</Name><GovernorateName>ينبع البحر</GovernorateName></City><City><Id>9605</Id><Name>ينبع الصناعية</Name><GovernorateName>ينبع البحر</GovernorateName></City> </Cities> </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
CodeDescriptionSolution400Bad RequestThe 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. Make sure you are subscribed to an API you are trying to call and provide the right key."Ensure that a valid access token is being used in your API call.403Total limit for calls for your subscription has been reached.You've reached the total limit of calls for web services. Based on your subscription type you have a defined number of calls which can be made. Please refer to “Products” section to know more about your subscription.404Page not foundThe endpoint or resource your application is trying to reach doesn't exist.500Internal Service ErrorThere was an application error on our server. Usually your request is valid but needs to be made at a later time.
By catching 401 unauthorized exceptions in all your calls you'll provide the coverage you need in your application to handle expired tokens. It's good practice to design and develop your application in anticipation that with any request you could potentially have an invalid access token.