Introduction
The Maltapark API is organised into endpoints with the following top-level URIs:
/properties
Use this API to obtain lists of properties that can be used elsewhere in the API. These are typically lists of [key,value] pairs. Examples are these are generic lists such as 'sections' or 'categories' or more specific lists such as vehicle transmission types. For example, to create a listing for a vehicle for sale, one of the required parameters is the transmission type. For this parameter you would be required to specify the key of one of the entries in this list.
/sections
Use this API to obtain information about the numeric key values associated with the different listing sections (Classifieds, Cars & Parts, Properties & Jobs). You will be expected to use the numeric key value when a SectionID parameter is requested in other parts of the API.
/listings
Use this API to read, modify or add listings.
/user
Use this API to read, modify or update properties related to the authenticated user.
Authentication
Authentication for the API follows the oAuth2 specification.
|
All requests to our API need to be authenticated using an authentication token obtained through one of two authentication methods. |
Client authentication is an authentication method that does not require any user credentials. This authentication method can be used for operations that are not user-specific, such as getting a list of categories.
User authentication is an authentication method that requires the account holder’s username and password and is used for operations that are user-specific, such as adding a listing or getting a user’s details.
If a token obtained from client authentication is used in a user-specific operation, this will result in a 401 - Unauthorised error.
If an operation is attempted without a token or with an expired token, this will also result in a 401 - Unauthorised error.
A token obtained from user authentication can be used in any kind of operation.
|
The authentication token is specified in the HTTP request as an "Authorisation" header parameter with a value of "Bearer token", where token is the authentication token (oAuth2 Bearer Token). |
Authentication tokens expire after a set time. The authentication token response includes the expiry time expressed in number of seconds from the time the token was issued. The autentication response also contains a refresh token that can be used to obtain a new authentication token when the first one expires.
To obtain the Client ID and Client Secret required for authentication, create an Application on the API pages of our portal. Developers should use each client id / secret pair for one specific application. Other client id / secret pairs can be created for different applications.
Client authentication (oAuth2 Client Credentials Grant)
Use this form of authentication to perform operations that are not related to a specific user account.
POST /v1/token
Parameters
| Type | Name | Value | Schema |
|---|---|---|---|
Header |
grant_type |
client_credentials |
string |
Header |
client_id |
your client id |
string |
Header |
client_secret |
your client secret |
string |
User authentication (oAuth2 Resource Owner Credentials Grant)
Use this form of authentication to perform operations that are related to your user account. Use your usual login username and password (as well as your client_id and client_secret), to obtain an authentication token.
POST /v1/token
Parameters
| Type | Name | Value | Schema |
|---|---|---|---|
Header |
grant_type |
password |
string |
Header |
client_id |
your client id |
string |
Header |
client_secret |
your client secret |
string |
Header |
username |
your username |
string |
Header |
password |
your password |
string |
Refresh Token Authentication (oAuth2 Refresh Token Grant)
Use this form of authentication to obtain an authentication token from a refresh token.
POST /v1/token
Parameters
| Type | Name | Value | Schema |
|---|---|---|---|
Header |
grant_type |
refresh_token |
string |
Header |
client_id |
your client id |
string |
Header |
client_secret |
your client secret |
string |
Header |
refresh_token |
your refresh token |
string |
Test Mode
If the application is set to "Test Mode" on the API pages, listings created using the API are test listings that do not appear in searches in the live website, but still appear in "My Listings". Developers should use "Test Mode" for all development and testing until the application is released to production. All other operations are unaffected by the "Test Mode" setting. For example, you can still delete live listings when in test mode. Caution is therefore advised if using an active and populated account for testing purposes.
|
There is a limit to the number of active test listings that you can have on an account. If the limit is exceeded, the API will return an error. In such a case, just delete some tests (from 'My Listings' or using the API itself), before adding some others. Once the API 'Test Mode' is turned off, the limit no longer applies. |
API Endpoints
Paths
Create a listing.
POST /v1/listings
Get information about a listing.
GET /v1/listings/definition/{id}
Delete several listings.
POST /v1/listings/delete
Return the photo allowances for a specific section and category.
GET /v1/listings/photospecs
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
categoryid |
Category ID |
integer (int64) |
Query |
sectionid |
Section ID |
integer (int64) |
Relist several expired listings.
POST /v1/listings/relist
Relist all expired listings.
POST /v1/listings/relistall
Unwatch several listings.
POST /v1/listings/unwatchmulti
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Body |
watchitems |
Item IDs to be unwatched |
< WatchItem > array |
Validate properties of a listing before publishing.
POST /v1/listings/validate
Watch several listings.
POST /v1/listings/watchmulti
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Body |
watchitems |
Item IDs to be watched |
< WatchItem > array |
Get detailed information about a listing.
GET /v1/listings/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
Listing ID |
integer (int64) |
Query |
related |
Number of related listings to obtain |
integer (int32) |
Get short information about a listing.
GET /v1/listings/{id}/mini
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
Listing ID |
integer (int64) |
Query |
agentid |
Agent ID (if not owner) |
integer (int64) |
Upload a single photo for a listing.
POST /v1/listings/{id}/photos
Delete a photo for a listing.
DELETE /v1/listings/{id}/photos/{index}
Rotate a photo for a listing.
POST /v1/listings/{id}/photos/{index}/rotate
Set the default photo for a listing.
POST /v1/listings/{id}/photos/{index}/setdefault
Set premium options for a listing.
POST /v1/listings/{id}/premiumoptions
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
Listing ID |
integer (int64) |
Body |
req |
PremiumOptionsRequest |
Get current premium options for a listing.
GET /v1/listings/{id}/premiumoptions
Get user-specific information about a listing.
GET /v1/listings/{id}/userinfo
Get the list of candidate statuses
GET /v1/properties/candidatestatus
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of categories, ordered by section.
GET /v1/properties/categories
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the categories for a given section.
GET /v1/properties/categories/{id}
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of doors options for vehicle listings
GET /v1/properties/doors
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the list of education levels
GET /v1/properties/education
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the list of price filters for various categories
GET /v1/properties/filterprices
Get the full list of fuel options for vehicle listings
GET /v1/properties/fuel
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the list of imported options for vehicle listings
GET /v1/properties/imported
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the list of job types
GET /v1/properties/jobtypes
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of localities for a country. Use 125 for Malta.
GET /v1/properties/localities
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of bedroom options
GET /v1/properties/propertybedrooms
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of finish options
GET /v1/properties/propertyfinish
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of garden options
GET /v1/properties/propertygarden
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of pool options
GET /v1/properties/propertypool
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of property types
GET /v1/properties/propertytypes
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of regions for a country. Use 125 for Malta.
GET /v1/properties/regions
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of transmission options for vehicle listings
GET /v1/properties/transmission
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of car makes
GET /v1/properties/vehiclemakes
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of car models
GET /v1/properties/vehiclemodels
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< StringId > array |
Get the full list of sections, or the section of a given type.
GET /v1/sections
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
< Section > array |
Get details of a specific section.
GET /v1/sections/{id}
Query information about an authorisation token
GET /v1/token/query
Get list of account transactions for the authenticated user
GET /v1/user/account
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
count |
Count of records to retrieve |
integer (int32) |
Query |
first |
Index of first record to retrieve (0-based) |
integer (int32) |
Update details for authenticated user
POST /v1/user/details
Get details for authenticated user
GET /v1/user/details
Get the invoice for a specific order
GET /v1/user/invoice
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
invoicetype |
0 = invoice, 1 = proforma |
integer (int32) |
Query |
orderid |
Order ID |
integer (int32) |
Get listings for authenticated user
GET /v1/user/listings
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
count |
Count to retrieve |
integer (int32) |
Query |
filter |
Text filter |
string |
Query |
first |
Index of first record to retrieve (1-based) |
integer (int32) |
Query |
section |
Section ID to retrieve |
integer (int64) |
Query |
sortmode |
0 = MostRecent, 1 = Lowest Price, 2 = Highest Price0 = MostRecent, 1 = PriceLow, 2 = PriceHigh, 3 = ItemAlpha |
enum (0, 1, 2, 3) |
Query |
viewmode |
0 = ShowAll, 1 = Expired0 = ShowAll, 1 = ShowExpired |
enum (0, 1) |
Get the cost of a premium option
GET /v1/user/premiumoptionscost
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
options |
List of premium options (enum) |
< integer (int32) > array(multi) |
Update the profile picture for the authenticated user
POST /v1/user/profilepicture
Get list of section IDs in which user has listings
GET /v1/user/sections
Get a single watched listing by ID
GET /v1/user/watchedlisting/{id}
Definitions
AccountEntry
| Name | Schema |
|---|---|
Amount |
number (double) |
Balance |
number (double) |
Description |
string |
ReceiptUrl |
string |
TimeStamp |
string (date-time) |
AccountResult
| Name | Schema |
|---|---|
AccountEntries |
< AccountEntry > array |
Balance |
number (double) |
CompanyDetails
| Name | Description | Schema |
|---|---|---|
CompanyType |
0 = Undefined, 1 = Recruiter, 2 = Property, 3 = CarAgent, 9 = OtherCompany, 10 = Individual |
integer (int32) |
Id |
integer (int64) |
|
Logo |
string |
|
Name |
string |
CreateOrUpdateResult
| Name | Schema |
|---|---|
Error |
string |
PKID |
integer (int64) |
Success |
boolean |
ValidationResults |
Image
| Name | Description | Schema |
|---|---|---|
Index |
integer (int32) |
|
Main |
boolean |
|
SizeClass |
0 = FullSize, 1 = ThumbSize |
integer (int32) |
Url |
string |
ItemDetail
| Name | Description | Schema |
|---|---|---|
CategoryId |
integer (int64) |
|
CategoryName |
string |
|
Company |
||
Condition |
0 = NA, 1 = Used, 2 = New, -1 = Any |
integer (int32) |
Contacts |
< ContactDetails > array |
|
DateAdded |
string |
|
Description |
string |
|
ExtraParamsType |
0 = None, 1 = Vehicle, 2 = Property |
integer (int32) |
ImageUrls |
< string > array |
|
IsWanted |
boolean |
|
N_Params |
||
PKID |
integer (int64) |
|
Price |
number (double) |
|
PriceSuffix |
string |
|
Related |
< ListItem > array |
|
S_Params |
||
SectionId |
integer (int64) |
|
SectionName |
string |
|
Seller |
string |
|
SellerType |
string |
|
Telephone |
string |
|
Telephones |
< string > array |
|
Title |
string |
|
Url |
string |
|
User |
||
Views |
integer (int32) |
ItemExtraParams
| Name | Schema |
|---|---|
Labels |
< string > array |
Names |
< string > array |
Text |
< string > array |
Values |
< string > array |
ItemMiniData
| Name | Schema |
|---|---|
Border |
boolean |
Desc |
string |
DetailsUrl |
string |
FullPhotoUrl |
string |
IsPriceSpecified |
boolean |
ItemDeleted |
boolean |
ItemFound |
boolean |
Name |
string |
PhotoUrl |
string |
Price |
string |
Seller |
string |
SellerID |
integer (int64) |
UniqueID |
integer (int64) |
ListItem
| Name | Description | Schema |
|---|---|---|
CategoryId |
integer (int32) |
|
DateAddedUTC |
string |
|
Description |
string |
|
ExtraParamsType |
0 = None, 1 = Vehicle, 2 = Property |
integer (int32) |
FullImageUrl |
string |
|
ImageUrl |
string |
|
IsHighlighted |
boolean |
|
IsWanted |
boolean |
|
IsWatched |
boolean |
|
N_Params |
||
PKID |
integer (int64) |
|
Price |
number (double) |
|
PriceSuffix |
string |
|
S_Params |
||
SectionId |
integer (int32) |
|
Title |
string |
ListingDefinition
| Name | Description | Schema |
|---|---|---|
AssignedUserOrGroupId |
integer (int64) |
|
Bedrooms |
integer (int32) |
|
CategoryId |
integer (int64) |
|
CompanyProfileId |
integer (int64) |
|
Condition |
0 = NA, 1 = Used, 2 = New, -1 = Any |
integer (int32) |
ContactTel |
string |
|
Description |
string |
|
Doors |
integer (int32) |
|
EngineSize |
integer (int32) |
|
FinishLevel |
integer (int32) |
|
FirstListedUTC |
string |
|
Fuel |
integer (int32) |
|
GardenOrYard |
integer (int32) |
|
Images |
< < Image > array > array |
|
Imported |
integer (int32) |
|
LocalityId |
integer (int64) |
|
Mileage |
integer (int32) |
|
PKID |
integer (int64) |
|
PaymentAuth |
0 = Undefined, 1 = NotRequired, 2 = Authorised |
integer (int32) |
Pool |
integer (int32) |
|
Price |
number (double) |
|
PriceLabel |
0 = None, 1 = PerDay, 2 = PerWeek, 3 = PerMonth |
integer (int32) |
PropertyType |
integer (int32) |
|
RegYear |
integer (int32) |
|
RelistedUTC |
string |
|
SectionId |
integer (int64) |
|
Title |
string |
|
Transmission |
integer (int32) |
|
UserRef |
string |
|
VehicleMake |
string |
|
VehicleModel |
string |
|
Views |
integer (int32) |
ListingResults
| Name | Schema |
|---|---|
CategoryCounts |
< < integer (int32) > array > array |
Items |
< ListItem > array |
LastResultID |
integer (int64) |
MainCategory |
integer (int64) |
MainSecType |
string |
MainSection |
integer (int64) |
Results |
integer (int32) |
TotalResults |
integer (int32) |
ListingUserInfo
| Name | Schema |
|---|---|
IsWatching |
boolean |
ReceivedMsgs |
integer (int32) |
StartedThreads |
< UserThread > array |
UnreadMsgs |
integer (int32) |
Locality
| Name | Schema |
|---|---|
CountryId |
integer (int32) |
Id |
integer (int32) |
Name |
string |
RegionId |
integer (int32) |
MultiListingActionResult
| Name | Description | Schema |
|---|---|---|
Errors |
< ItemError > array |
|
Items |
< integer (int64) > array |
|
Result |
0 = Success, 1 = Failure, 2 = PartialSuccess |
integer (int32) |
MultiListingRequest
| Name | Description | Schema |
|---|---|---|
Items |
< integer (int64) > array |
|
PaymentAuth |
0 = Undefined, 1 = NotRequired, 2 = Authorised |
integer (int32) |
PhotoSpecs
| Name | Schema |
|---|---|
Max |
integer (int32) |
MaxHeight |
integer (int32) |
MaxWidth |
integer (int32) |
Min |
integer (int32) |
PostUserDetailsRequest
| Name | Schema |
|---|---|
AccountType |
string |
Company |
string |
Name |
string |
Telephone |
string |
VatNumber |
string |
PremiumOptionStatus
| Name | Description | Schema |
|---|---|---|
Active |
boolean |
|
Expires |
boolean |
|
Expiry |
string (date-time) |
|
Option |
0 = None, 1 = Featured_3days, 2 = Featured_7days, 3 = Featured |
integer (int32) |
PremiumOptionsStatusResult
| Name | Schema |
|---|---|
options |
< PremiumOptionStatus > array |
PropertiesCollection
| Name | Schema |
|---|---|
FilterPrices_Cars |
< integer (int64) > array |
FilterPrices_PropertyForSale |
< integer (int64) > array |
FilterPrices_PropertyLongLet |
< integer (int64) > array |
FilterPrices_PropertyShortLet |
< integer (int64) > array |
JobCandidateStatus |
< StringId > array |
JobEducation |
< StringId > array |
JobTypes |
< StringId > array |
Localities |
< Locality > array |
PropertyBedrooms |
< StringId > array |
PropertyFinish |
< StringId > array |
PropertyGarden |
< StringId > array |
PropertyPool |
< StringId > array |
PropertyTypes |
< StringId > array |
Regions |
< Region > array |
VehicleDoors |
< StringId > array |
VehicleFuel |
< StringId > array |
VehicleImported |
< StringId > array |
VehicleMakes |
< string > array |
VehicleModels |
< VehicleModel > array |
VehicleTransmission |
< StringId > array |
RelistAllRequest
| Name | Description | Schema |
|---|---|---|
PaymentAuth |
0 = Undefined, 1 = NotRequired, 2 = Authorised |
integer (int32) |
TokenResponse
| Name | Schema |
|---|---|
Access_token |
string |
Error |
string |
Error_description |
string |
Expires_in |
integer (int32) |
HasShares |
boolean |
Identity |
integer (int64) |
Message |
string |
OwnerId |
integer (int64) |
OwnerUsername |
string |
Refresh_token |
string |
ThirdPartyProfilePic |
string |
Token_type |
string |
Username |
string |
UserDetailsResponse
| Name | Description | Schema |
|---|---|---|
AccountType |
string |
|
Balance |
number (float) |
|
Companies |
< CompanyDetails > array |
|
Company |
string |
|
Email |
string |
|
Name |
string |
|
ProfileImage |
string |
|
PropertySellerType |
0 = NotDefined, 1 = Owner, 2 = Broker, 3 = Developer, 4 = Agent, 5 = MainAgencyAC |
integer (int32) |
PropertySellerTypeLocked |
boolean |
|
SharedUsers |
< SharedUser > array |
|
TelRestricted |
boolean |
|
TelRestrictedUntil |
string |
|
TelVerified |
string |
|
Telephone |
string |
|
UserID |
integer (int64) |
|
Username |
string |
|
VatNumber |
string |
UserPublicProfile
| Name | Schema |
|---|---|
Company |
string |
ItemCount |
integer (int32) |
PictureUrl |
string |
RegistrationDate |
string (date-time) |
UserId |
integer (int64) |
Username |
string |
UserSectionsResponse
| Name | Schema |
|---|---|
Expired |
< integer (int32) > array |
SectionNames |
< string > array |
Sections |
< integer (int64) > array |
ValidateResult
| Name | Description | Schema |
|---|---|---|
Error |
string |
|
ErrorType |
0 = OK, 1 = Required, 2 = Invalid |
integer (int32) |
Field |
string |
ValidateResults
| Name | Schema |
|---|---|
CanProceed |
boolean |
Results |
< ValidateResult > array |
Specific Parameters / Filters
|
These lists can also be obtained using the Properties API. This will ensure your implementation remains up to date. |
Property Parameters
| Parameter | Type | Values |
|---|---|---|
Property Type |
int |
1=Apartment / Flat, 2=Maisonette, 3=Terraced House, 4=Semi-Detached Villa, 5=Detached Villa, 6=House of character, 11=Penthouse, 12=Bungalow, 13=Palazzo, 14=Garage, 7=Offices, 8=Business Outlet or Shop, 9=Industrial, 10=Other Commercial, 20=Plot, 21=Land (ODZ), 99=Other |
Bedrooms |
int |
1,2,3,4,5,6,0=Not Applicable |
Locality |
int |
Use Properties API for applicable values |
Garden/Yard |
int |
1=No,2=Yes,9=Not Applicable |
Level of Finish |
int |
1=Site/Land, 2=Shell, 3=Semi-Finished, 4=Finished, 5=Furnished, 99=Other |
Pool |
int |
1=No, 2=Yes, 3=Not Applicable |
Vehicle Parameters
| Parameter | Type | Values |
|---|---|---|
Reg. Year |
int |
4-digit year of registration |
Fuel |
int |
"0=Petrol", "1=Diesel", "2=Electric", "3=Dual Fuel" |
Mileage |
int |
Mileage in km |
Doors |
int |
"2=2 doors", "3=3 doors", "4=4 doors", "5=5 doors" |
Engine Size |
int |
Engine size in cc |
Transmission |
int |
"0=Manual", "1=Auto", "2=Semi-Auto" |
Imported |
int |
0=No", "1=UK Import", "2=Japan Import", "99=Other Import" |
Vehicle Make |
string |
Use Properties API for applicable values |
Vehicle Model |
string |
Use Properties API for applicable values |