POI's Free Text Search
POI's free text search allows user to find availability of a service he is looking for by providing details of service as a free text string input. This API can help developers in guiding their customers to nearest location of service they are looking for example banking or pharmacy. 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(optional)
It’s an optional input. Our API’s can provide response in Arabic or English with Arabic being the default language.
Subscription Key
Access token to authenticate you as a valid user of the system. Please refer to profile section to get your subscription key.
page
It’s an optional input. By default each request returns a maximum number of 10 results. If there are a large number of results, in such a case, this page number must be passed along to get the next set of results. Default value is 1.
Servicestring
Service as string.
encode(optional)
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/address/poi-free-text?language=E&format=JSON&page=1&servicestring=saudi+post&api_key=Response
Default Fields Returned
By default, only the following fields are returned for a profile request:
Field
Description
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.
totalSearchResults
By default, each search request returns a set of 10 results. In case of multiple results, this attribute will describe the total number of results, so that the developer can pass the page number to get the next set of results accordingly.
Title
Alias name of landmark/service. Example atm (national comm. bank).
Address(Part 1)
This consists of the first line of Saudi Post format of address.” [BuildingNumber] [Street] - [District]”.
Address(Part 2)
This consists of the second line of Saudi Post format of address.”[City] [PostCode] – [AdditionalNumber]”.
ObjLatLng
This consists of latitude and longitude details of the address. To enable user to plot it on any map application like google map. [ObjectId] [Longitude] [Latitude] [Minx] [Miny] [Maxx] [Maxy].BuildingNumberFour digit number which is unique to a building.
Street
Name of the street on which building is. Example king abdul aziz road.
District
Name of the district in which address falls. Example al amal.
City
Name of the city in which address falls. Example Riyadh.
PostCode
Five digits numerical Post code / Zip Code.
AdditionalNumber
Four digit number.
RegionName
Name of region in which address falls. Example Ar Riyadh.
BuildingNumber
Four digit number which is unique to a building.
Latitude
Angular distance of the equator of a celestial object – expressed in degrees. Example 24.650099667616
Longitude
Angular distance of a place east or west of the meridian. Example 46.7166631947852
CityId
Id of the city in which address falls. Example: 3
RegionId
Id of the region in which address falls. Example 1
PKAddressID
Primary key for address. Example : 1264382282121
DistrictID
District Id in which address falls. Example : 10100003001
RegionName_L2
Region name in which address falls with another available language from default.
City_L2
City name in which address falls with another available language from default.
Street_L2
Street name in which address falls with another available language from default.
District_L2
District name in which address falls with another available language from default.
Title_L2
Title name in which address falls with another available language from default.
Sample Response
JSON
{"totalSearchResults": "1", "Addresses": [{"Title":"Saudi Post","Address1":"6687 Al Adel - As Sukhayrat Dist.","Address2":"AL ULA 43522 - 2765","ObjLatLng":"37.9258111000001 26.6084492000002","BuildingNumber":"6687","Street":"Al Adel","District":"As Sukhayrat Dist.","City":"AL ULA","PostCode":"43522","AdditionalNumber":"2765","RegionName":"Madinah","PolygonString":null,"IsPrimaryAddress":null,"UnitNumber":null,"Latitude":"26.6084492000002","Longitude":"37.9258111000001","CityId":"199","RegionId":"3","Restriction":null,"PKAddressID":"4352266872765","DistrictID":"10300199002","Title_L2":"البريد السعودي","RegionName_L2":" المدينة المنورة","City_L2":"العلا","Street_L2":"العدل","District_L2":"حي الصخيرات","CompanyName_L2":null,"GovernorateID":null,"Governorate":null,"Governorate_L2":null}, "PostCode": null, "success": true, "statusdescription": "SUCCESS"}
XML
<AddressOutPutParams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"> <success>true</success> <statusdescription>SUCCESS</statusdescription> <totalSearchResults>1</totalSearchResults> <Addresses><Address><Title>Saudi Post</Title><Address1>6687 Al Adel - As Sukhayrat Dist.</Address1><Address2>AL ULA 43522 - 2765</Address2><ObjLatLng>37.9258111000001 26.608492000002</ObjLatLng><BuildingNumber>6687</BuildingNumber><Street>Al Adel</Street><District>As Sukhayrat Dist.</District><City>AL ULA</City><PostCode>43522</PostCode><AdditionalNumber>2765</AdditionalNumber><RegionName>Madinah</RegionName><Latitude>26.6084492000002</Latitude><Longitude>37.9258111000001</Longitude><CityId>199</CityId><RegionId>3</RegionId><PKAddressID>4352266872765</PKAddressID><DistrictID>10300199002</DistrictID><Title_L2>البريد السعودي</Title_L2><RegionName_L2> المدينة المنورة</RegionName_L2><City_L2>العلا</City_L2><Street_L2>العدل</Street_L2><District_L2>حي الصخيرات</District_L2></Address></Addresses> </AddressOutPutParams>
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 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.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.