Weekly Featured Properties - Tech documentation

Silver__Gold_and_Platinum_Membership_package_holders.png

An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries.  It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.  

The Weekly Featured Properties API enables you to programmatically activate weekly features properties directly within your internal CRM.  

Use the Weekly Featured Properties API to: 

  • Activate the Weekly Featured Property product, subject to available credits
  • Check if a listing has a weekly featured property product activated
  • Get a history of your weekly featured property product activations

 Note

The API work is still in progress and details provided in this documentation are subject to change

This article includes: 

Prerequisites

This article assumes you have a general knowledge of command line interfaces and software development.  

Authentication

The first step of working with the Weekly Featured Properties API is to set up authentication for your client.  Please follow the steps in Authentication - Tech Documentation.  

Working with the API

The API is asynchronous.  What does this mean? When you make a request to activate a weekly featured property listing, we validate the request and place it in a queue for further processing, returning a status of PENDING

Once processed, there are two possible statuses: 

  • ACTIVATED which means the weekly featured property you specified is now line on the Zoopla website
  • ERROR which suggests an issue occurred during the operation. More details are provided in the response

The sequence diagram below provides an overview of how the API works: 

how-to-work-with-this-api.JPG

Available endpoints 

Below you will find details about the requested payload and responses as shown in the sequence diagram above.  

Request weekly featured property activation - request [004] 

Method: POST 

Path: /products/weekly-featured-properties

Payload: 

}
"listingId":123
}

To activate the weekly featured property product, a unique request must be made for each listing and include the relevant listingId.

Validation rules:

You cannot request to activate the weekly featured property product in the event: 

  1. The listingId doesn't exist or is invalid
  2. The client doesn't have access to the listing
  3. A listingId has an activation status of PENDING
  4. The weekly featured property product is already active for that specific listing 

The listingId is required in all circumstances.  

Example cURL request: 

curl --location --request POST 'https://services.zoopla.co.uk/products/weekly-featured-properties' \ 
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJMU0VyUkowYk5ubkg0UGorUUZObXdnd08wNk1UdXBoNVJJOERlRGp3ZXg4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIzNG9iYXJlbGNkN3BuanJxZmYwNjZqdWljdiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXBpXC9hcGlfYWNjZXNzIiwiYXV0aF90aW1lIjoxNTk1MjQ0MjMwLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9nMHFlWlJuYlQiLCJleHAiOjE1OTUyNDc4MzAsImlhdCI6MTU5NTI0NDIzMCwidmVyc2lvbiI6MiwianRpIjoiNjAyYmYzMjItYWI4ZC00MDBlLWJiODEtZjE2NTc4ZjM1MDAyIiwiY2xpZW50X2lkIjoiMzRvYmFyZWxjZDdwbmpycWZmMDY2anVpY3YifQ.puj4abAiORSAS0zuXCFAbhwai9Nf29RcVV4XkOsLd_Xl8oAwswzKARg3hKLMsRadoIc8qk7OFASg594j0aoutqcceyhsg6zBn6kt-INfwiNJ0pIjUAxVDKglZQk3dLJWQffLTFCzXNsxhB5lAWP4IHHSBgkDh8_EQ5d5UyDI5urn1zOT8bbH3aXpF6YUWfZDVPSqobB5y_Tky1lLvxtqkQQwFPppRW8r-PGrI__zljtFATCeJOw9GrnM9UNBtk76s0G43ox4PmlzD9Viu7Y15vWjy2kHbkxaCHoCXVOaM1nT2GsRp_1E_DKiF7vzEzSfkD_mdCDM5dbhuEiLvZgVLw' \
--data-raw '{
"listingId": 123
}'

Get details of weekly featured property activation - request [008]

Path: /products/weekly-featured-properties/{weeklyFeaturedPropertiesUUID}

Example response: 200 OK

When a request is still PENDING

{ 
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "PENDING"
}
}

When a request is completed and status is ACTIVATED

{ 
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00"
}

When a request is completed but there was a problem during weekly featured property activation

{ 
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ERROR",
"errors": [
{
"reason": "Listing ID doesn't exist",
"code": 2011011
}
]
}
}

When there is already a pending weekly featured property activation for the listingId

{ 
"errors": [
{
"reason": "There is already a weekly featured property activation pending for this listing ID",
"code": 2011004
}
]
}

Get all weekly featured property activations

There is also an endpoint which allows you to get all requests to activate the weekly featured property product the user has access to. 

Method: Get 

Path: /products/weekly-featured-properties

Example Response: 200 OK 

[ 
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 567,
"createdAt": "2020-07-17T12:35:38.049963+01:00",
"updatedAt": "2020-07-17T12:35:38.049963+01:00",
"status": {
"result": "PENDING"
}
},
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00"
}
]

You can narrow the number of objects in the array by providing query parameters

  • listingId - return only activation requests related to the given listingId
  • isWFP  - return only activations which are currently effectively active

Both parameters can be combined in one request, and in such case, parameters are connected with logical AND. Further information on how to use parameters can be found below/ 

Example request: /products/weekly-featured/properties?listingId=123  

[ 
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00"
}
]

 Note

API does not support pagination yet.  This is going to be defined

How to check is the listing is activated as a Weekly Featured Property

Using endpoint /products/weel;y-featured-properites provides the activation status if a listing without knowing the activation request uuid.  

The check if  a specific listingId is a weekly featured proeprty, the following request can be used: 

GET https://services.zoopla.co.uk/products/weekly-featured-properties?listingId=123&isWFP=true

If listing 123 is a weekly featured property the response will look like this: 

[ 
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00"
}
]

If listing 123 is not a weekly featured property, the response will look like this: 

[]

Errors

In case of an issue with the request, for example, validation failure, you can expect the JSON response to include details of the error.  Example response: 

{ 
"errors": [
"reason": "Internal error interpreting JSON data",
"code": 2011016
]
}

See Weekly Featured Properties error code register for a complete list of all error codes and their meaning. 

Questions

If you have any questions related to this tech documentation / API, please contact members@zoopla.co.uk

Was this article helpful?
0 out of 0 found this helpful