Free Text Search

Free text search allows a user to find complete details of an address by providing limited details about an address as a free text. Using the service user can complete an address to enable its user to reach there comfortably even if they know only some details about it. 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

Requested URL

https://apina.address.gov.sa/NationalAddress/v3.1/address/address-free-text?language=E&format=JSON&page=1&addressstring=8228+12643&api_key=

https://apina.address.gov.sa/NationalAddress/v4/address/address-free-text?language=E&format=JSON&page=1&addressstring=8228+12643&api_key=

Response

Default Fields Returned

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

Sample Response
JSON

{"totalSearchResults": "1",
"Addresses": [{"Title": null,
"Address1": "8228 king abdul aziz road - al amal",
"Address2": "riyadh 12643 - 2121",
"ObjLatLng": "30829 46.71670870 24.65017630",
"BuildingNumber": "8228",
"Street": "king abdul aziz road",
"District": "al amal",
"City": "riyadh",
"PostCode": "12643",
"AdditionalNumber": "2121",
"RegionName": "Ar Riyadh ",
"PolygonString": null}],
"PostCode": null,
"success": true,
"datasetOrdatatable": null,
"result": null,
"statusdescription": "SUCCESS",
"fullexception": null}

Response for version v4

{
  "totalSearchResults": "1",
  "Addresses": [
    {
      "Address1": "8228 طريق الملك عبدالعزيز - ",
      "Address2": "الرياض 12643 - 2121",
      "ObjLatLng": "3164485 46.7166631947852 24.650099667616",
      "BuildingNumber": "8228",
      "Street": "طريق الملك عبدالعزيز",
      "District": "العمل",
      "City": "الرياض",
      "PostCode": "12643",
      "AdditionalNumber": "2121",
      "RegionName": ""
    }
  ],
  "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>
<Address1>8228 king abdul aziz road - al amal</Address1>
<Address2>riyadh 12643 - 2121</Address2>
<ObjLatLng>30829 46.71670870 24.65017630</ObjLatLng>
<BuildingNumber>8228</BuildingNumber>
<Street>king abdul aziz road</Street>
<District>al amal</District>
<City>riyadh</City>
<PostCode>12643</PostCode>
<AdditionalNumber>2121</AdditionalNumber>
<RegionName>Ar Riyadh</RegionName>
</Address>
</Addresses>
</AddressOutPutParams>

Response for version v4

<ApiSearchResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/SPLocatorAPI.Models">
	<statusdescription>SUCCESS</statusdescription>
	<success>true</success>
	<Addresses>
		<Address>
			<AdditionalNumber>2121</AdditionalNumber>
			<Address1>8228 طريق الملك عبدالعزيز - </Address1>
			<Address2>الرياض 12643 - 2121</Address2>
			<BuildingNumber>8228</BuildingNumber>
			<City>الرياض</City>
			<District>العمل</District>
			<ObjLatLng>3164485 46.7166631947852 24.650099667616</ObjLatLng>
			<PostCode>12643</PostCode>
			<RegionName></RegionName>
			<Street>طريق الملك عبدالعزيز</Street>
		</Address>
	</Addresses>
	<totalSearchResults>1</totalSearchResults>
</ApiSearchResult>    

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.