Identify

Retrieve an address in NA address json format for a given latitude and longitude.

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. 

API Request 
Input Parameters

Field Description
lat The latitude value for the address, sample: 24.706754
lon The longitude value for the address, sample: 46.812660
Authorization Bearer token
api_key Access token to authenticate you as a valid user of the system. Please refer to profile section to get your subscription key.

 

Requested URL

https://apina.address.gov.sa/identify?lat=<latitude>&lon=<longitude>&api_key=<apikey>

Response

Default Fields Returned

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

FieldDescription
success This represents success or failure of the request itself (true/false).
message This represents success or failure of the request itself (true/false).
naIdentifyResult The National Address object with following fields
addressID The unique address id.
buildingNumber The building number feild.
additionalNumber The additional number feild.
zipCode The zipcode feild.
restriction The field represent the restriction on address.
districtID The district Id on which the address falls.
cityId The city Id on which the address falls.
regionId The region Id on which the address falls.
shortAddress The short address for the address.
streetNameArabic The street name in arabic language.
streetNameEnglish The street name in english language.
districtNameArabic The district name in arabic language.
districtNameEnglish The district name in english language.
cityNameArabic The city name in arabic language.
cityNameEnglish The city name in english language.
regionNameArabic The region name in arabic language.
regionNameEnglish The region name in english language.

Sample Response
JSON

{
    "naIdentifyResult": {
        "addressID": "2906586",
        "buildingNumber": "3568",
        "additionalNumber": "8636",
        "zipCode": "13447",
        "restriction": "No",
        "districtID": "10100003149",
        "cityId": "3",
        "regionId": "1",
        "shortAddress": "RUKB3568",
        "streetNameArabic": "",
        "streetNameEnglish": "",
        "districtNameArabic": " مطار الملك خالد ",
        "districtNameEnglish": "King Khalid International Airport",
        "cityNameArabic": "الرياض ",
        "cityNameEnglish": "RIYADH",
        "regionNameArabic": null,
        "regionNameEnglish": null
    },
    "success": true,
    "message": null
}


Common Errors

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

CodeDescriptionSolution
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.
404 Page not found The endpoint or resource your application is trying to reach doesn't exist
405 Method Not Allowed.
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.