allAgents icon allAgents API

allAgents has introduced a RESTful API for its Premium Support Agents, so that they are better able to utilise the wealth of data allAgents has collected over the years.

Please find simple examples of the possible uses for the API in this section. Examples are provided in PHP using cURL, but the core concepts are the same and applicable regardless of client-side implementation. At the moment, the API outputs JSON responses only.


Where can I find my API key?

API Keys are only available to Premium Support Plus members, and can be retrieved from the firm or branch's logged-in area on allAgents. You can sign in here.

How do I use my API Key?

The API Key must be sent as an HTTP header, 'APIKEY: ...', and not as a POST variable or in the the request URL.


Important Usage Notes


  • The allAgents API will only work over the HTTPS protocol.
    Your website does not need to be using HTTPS, but calls to the API must go to https://www.allagents.co.uk/api/.... and not http://www.allagents.co.uk/api/....

  • All URLs must end with a trailing slash to receive a response.

  • allAgents enacts a rate limit in regard to requests. We will honour 200 requests per resource, per hour. There are also limits on smaller scales such that 200 requests can't be made in one minute, for example. If too many requests are made, you may receive temporary blocks to resources (after you have been notified). The reason for this is to keep the API healthy and responsive for all members.

  • It is strongly suggested that you cache our responses to avoid making unnecessary duplicate requests


  • You must link back to the original content when feeding reviews to you site, i.e. the branch or agent page from which the reviews originated. If you are allowing users to post a review from your site, it must be clear that the review is going to be submitted to allAgents, which must be linked to.

Resources


URL Description & Responses
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/
Retrieve details of your firm. A 'firm' refers to an estate or letting agency 'group' as a whole, and to no particular branch.

Response Field Description
name The name of the firm.
active_branches Number of branches belonging to the firm
onlineagent This is regarded as an online agent. Returns a 1 or 0 for true or false.
fee_satisfaction Customer satisfaction with fees, expressed as a percentage.
price_satisfaction Customer satisfaction with price sold, expressed as a percentage.
rank_uk Firm's rank in the UK.
rank_sales Firm's rank in regard to sales in the UK.
rank_let Firm's rank in regard to lettings in the UK.
rating Firm's overall average rating based on all customer reviews.
rating_sales Firm's average rating based on all customer reviews pertaining to sales transactions.
rating_let Firm's average rating based on all customer reviews pertaining to lettings transactions.
votes Number of reviews received, in any capacity.
votes_sales Number of reviews received pertaining to sales transactions
votes_let Number of reviews received pertaining to lettings transactions
GET
https://www.allagents.co.uk/api/v1/firms/your-firm-link/branches/your-branch-link/
Retrieve details of your branch. A branch refers to an estate or letting agency office with a particular address. All firms have at least one branch.

Response Field Description
address Street address of the branch.
district District/Locality of the branch within its town.
town Town in which the branch is located.
county County in which the branch is located.
postcode Full postcode of the branch
tel Telephone number of the branch
fax Fax number of the branch
rating The branch's overall average rating based on all customer reviews.
rating_sales Branch's average rating based on all customer reviews pertaining to sales transactions.
rating_let Branch's average rating based on all customer reviews pertaining to lettings transactions.
rank_sales Branch's rank in regard to sales in the UK.
rank_let Branch's rank in regard to lettings in the UK.
votes Number of reviews received for branch, in any capacity.
votes_sales Number of reviews for branch received pertaining to sales transactions
votes_let Number of reviews received for branch pertaining to lettings transactions
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/reviews/
Retrieve the latest 50 customer reviews left for your firm, regardless of which branch was reviewed. An array of up to 50 reviews is returned, with each item containing the following.

Response Field Description
name The display name of the reviewer.
date_added The date the review was published on allAgents.
review The review content.
capacity In what capacity the reviewer used the firm's services.
rating The reviewer's rating of the firm, from 1 star to 5.
willreturn Whether the reviewer would voluntarily return to use the firm's services again.
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/branches/[your-branch-link]/reviews/
Retrieve the latest 50 customer reviews left for your branch. An array of up to 50 reviews is returned, with each item containing the following.

Response Field Description
name The display name of the reviewer.
date_added The date the review was published on allAgents.
review The review content.
capacity In what capacity the reviewer used the branch's services.
rating The reviewer's rating of the branch, from 1 star to 5.
willreturn Whether the reviewer would voluntarily return to use the branch's services again.
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/branches/[your-branch-link]/markup/
Retrieve schema markup, which when added to your page, can improve its appearance in Google. Add this to branch-specific pages on your website, e.g. 'Croydon Branch'. Google can use the information to provide star ratings (based on your allAgents ratings and review count) for a page in its search results and information such as address and logo for the knowledge panel. Effects are not instant, and depend on Google. Check it has been applied correctly by using the Structured Data Tester Tool

Response Field Description
Not Applicable Print the result directly to the page. The result is in JSON-LD format. It is not visible to users, it is only visible in the source, which search engines can pick up.

Error Codes


Status / Error Explanation
100: An error has occurred This is the default catch-all error. If you encounter this error and are sure the request's URL is well-formed, please use your support package to submit details of your request.
101: API Key not received This error occurs when an API Key was not sent or received along with the request. The API Key must be sent as an HTTP header, in the form 'APIKEY: ####'.
102: Unable to validate API Key This error occurs when an API Key is not provided, the wrong or old key is used, or the API key is not enabled, e.g. not a premium support member. Also not that a firm's API Key is only valid for retrieving information regarding themselves.
103: Requested resource of type Firm not found The firm requested has not been found. Please check that the uRL path, in particular the reference following 'firms' corresponds to path of the firm's allAgents profile.
104: Requested resource of type Branch not found The branch requested has not been found for the firm requested. Please check that the uRL path, in particular the reference following 'branches' corresponds to path of the branch's allAgents profile.

Usage Examples


Please Sign In and click "API Info" in left menu to find usage examples in your branch account with credentials or contact us for your branch credentials.


Sell or Rent Your Property Via allAgents