This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
API models............................................................................................................................... 6brokers......................................................................................................................................6
GET list/searchFilterId...................................................................................................................................14
PUT list/searchFilterId...................................................................................................................................15
GET map/searchFilterId.................................................................................................................................16
PUT map/searchFilterId.................................................................................................................................16
POST list.........................................................................................................................................................16
POST map......................................................................................................................................................16
POST agent....................................................................................................................................................18
POST agent/searchFilterId.............................................................................................................................18
PUT agent/searchFilterId/name....................................................................................................................18
GET agent/list/searchFilterId.........................................................................................................................18
GET agent/map/searchFilterId......................................................................................................................18
GET notification/notificationId......................................................................................................................18
GET inbox.......................................................................................................................................................19
GET inbox/count............................................................................................................................................19
PUT inbox/notificationId...............................................................................................................................19
PUT inbox/all.................................................................................................................................................19
GET users/information..................................................................................................................................19
PUT users/information..................................................................................................................................19
POST users/login...........................................................................................................................................19
PUT users/login/changepassword.................................................................................................................19
POST users/login/forgotpassword................................................................................................................19
POST users/login/creation.............................................................................................................................20
GET users/devicetoken..................................................................................................................................20
POST users/devicetoken................................................................................................................................20
IntroductionThis document’s purpose is to describe Ejendomstorvet’s Partner API, its Endpoints and data in depth.
The API will provide most of its responses with error codes, messages and whether the input was valid, whenever possible. Errorcodes can be viewed in this document.
User Password hashingThe password of the user must be hashed before sending it through the API. The password is concatenated with a salt. The salt is as follows:
gdhfjkgdhfjk54785364fsdghjfsdgjh4534æøåThe algorithm for hashing goes like this
1) Concatenate the password with the salt2) Encode to bytes using the ANSII code page3) Hash using MD54) Remove any dashes ‘-‘ and change to uppercase
2) Encode to bytes using ANSI:41-6C-6C-59-6F-75-72-42-61-73-65-41-72-65-42-65-6C-6F-6E-67-54-6F-55-73-67-64-68-66-6A-6B-67-64-68-66-6A-6B-35-34-37-38-35-33-36-34-66-73-64-67-68-6A-66-73-64-67-6A-68-34-35-33-34-E6-F8-E5
3) Hash with MD5:5C-69-04-D8-55-9A-03-C2-F3-97-9C-03-54-B4-52-94
4) Remove any dash and change any letter to uppercase:5C6904D8559A03C2F3979C0354B45294
DefinitionsHere is an overview of what will be mentioned, and what specifically is described.
Any call (with minor exceptions) to the API, must contain the following headers:
HAWK ETUser
Word Description
Active A property is active, when the broker puts it “online”. If the property is not active, it is no longer for sale/rent.
ETUser Is a Guid and must be provided where applicable. On the API’s documentation (swagger), and in this document, it will be specified when this header may be left empty.
HAWK Header Is for authorization purposes. An API key is handed out by Sima.dk and must be stored safely on the Partner’s responsibility. Any misusage of the key can result in revoking of the key.
PricePrSqm / RentPrSqm
The PricePrSqm, and RentPrSqm are based around BaseArea if the property is of category “Parcel”. Otherwise it’s based around FloorArea
Partner The ‘Partner’ is the organization which has been given access to any of the Partner API’s. The partner is given a key and holds full responsibility for correct use of both the key and the API.
Portal www.ejendomstorvet.dk – the main site of Ejendomstorvet.
statusThis group of endpoints consists of one call which can be called anonymously (without HAWK- and ETUser headers).The call provides the Partner with local server time, whether they are online or not and where to find them.
property type DescriptionServerUtcTime DateTime UTC time according to the server.
Use this to ensure that the client and server agree on the time with a maximum difference of 5 minutes
MinimumAndroidVersion String The minimum versionnumber on Android that the client should allow.
MinimumiOSVersion String The minimum versionnumber on iOS that the client should allow.
ServiceEnvironments List of ServiceEnvironment Each ServiceEnvironment unveils data whether the environment is offline, the path, version and name.
The different environments are explained here:
DevelopThis environment will mostly be used for proof-of-concept and does not reflect the data on the portal, instead the data provided are all test-based data.
BetaThis environment reflects what’s to come, and serves as the name implies, as beta-testing. Data from this environment is based around what is on the portal.
ProductionThis environment reflects the portal as close as possible with minor differences. This should be used for any release-builds.
API modelsThe API Models can be seen by clicking on ”Model” under the methods’ respective requests in Swagger (marked yellow).
ViewPropertyUrl String The url to use when the user wishes to see details about the property.
IsHighlighted Boolean Returns true if this property is part of paid advertising in this list.
POSTInserts a favorite for a registered user using PropertyId. Returns 404 if the user was not found. Otherwise this returns 201
DELETERemoves the favorite for a user. 404 if the user is not registered. Otherwise this returns 204.
metadataReturns categories, intervals etc. All methods may omit using the ETUser header.
GETReturns one combined response of all below calls, divided into the respective PropertyTypes.
intervalsReturns a list of valid interval names which the API will expect. When using these in searchfilter, the minimum and maximum values will filter the results using the input values.
property type DescriptionName String The name to use when
doing requestsDisplayNameEN String The name to display in
EnglishDisplayNameDK String The name to display in
DanishDefaultMinimum Integer (32-bit) The default
minimumvalue of this interval
DefaultMaximum Integer (32-bit) The default maximumvalue of this interval
AbsoluteMinimum Integer (64-bit) The minimum value that should never be exceeded
AbsoluteMaximum Integer (64-bit) The maximum value that should never be exceeded
interesttypesReturns a list of valid interesttypes which the API will expect
property type DescriptionName String The name to use when
Returns a list of valid areas. Areas are locations of varying sizes that are not necessarily officially defined otherwise.
provinces
Returns a list of valid provinces
municipalities
Returns a list of valid municipalities
postals
Returns a list of valid postal codes and the names of the cities
wordtypesReturns a list of valid wordtypes as a list of strings.
NameCategorySubcategoryWordLocation
provincemunicsThis model returns a list of provinces, each with a list of municipalities or postals under which they belong
property type DescriptionGeoType GeoType View the geotypes section in this
documentGeoName String The name of the situation
searchwordSearchwords are modelled like this:
property type DescriptionWordId Integer (32-bit) The identifying key of the word.ParentId Integer (3-bit), nullable If applicable, this declares that the
word has a parent of the input idWordType WordType See the wordtypes section in this
documentWord String The word to display and use
searchwords/propertyTypeTo receive a list of suggestions to present the enduser, use this together with one of the valid propertytypes.
property type DescriptionSecondaryArea Integer (32-bit) The area of any secondary
properties that belong to this case.IsActive Boolean Indicates if this property is active.Latitude / Longitude Double Together, these describe the precise
location of the propertyIsSale Boolean Indicates if this property is for saleIsRental Boolean Indicates if this property is for rentEnergyMarks Array of strings The array of energy marks, if anyEnergyMarkLaw Boolean Indicates if energymarks are
required by law on this propertyReturn Double The return rate, in percentageIsProject Boolean Indicates if this property is a projectOperationCost Double Yearly costs to operate the propertyOperationCostPrSqm Double OperationCost, per squaremeterPropertyName String The name of the property, if anyMunicipality String The municipality in which this
property is placedDepriciation Boolean Indicates if this property can be
used for depreciationCaseNumber String The identifying casenumber, used by
the brokerConcealedBrokerMail String The broker’s mail, which has been
concealed. Call the /mail function to receive the mail unconcealed
ConcealedBrokerPhone String The broker’s phonenumber, which has been concealed. Call the /phone function to receive the phonenumber unconcealed
Facilities Array of strings Consists of a list of facilities that this property has
UsageExamples Array of strings A list of usage examples of the property
refTypes / PropertyLogRefTypeThe following values are allowed as refTypes, and is usually provided by the API:
Name DescriptionProperty Indicates that a user’s previous
display was about a propertyList Indicates that the user acted on a
listGallery Indicates interaction with a gallery –
this type is not provided by any of the API endpoints
Map Indicates interaction with a mapOther Fallback type indicating that the
interaction type is currently not supported by the API
Newest Indicates that a user interacted with a list of the newest properties
MatchingResults Indicates that a user interacted with a list of properties with matching category, pricerange and location
FrontPage Indicates that a user interacted with any property from a frontpage
Favorite Indicates that a user interacted with a property from their favorites list
Advert Indicates that a user interacted with a frontpage or a listing of an advert
AdvertOnProp Indicates an interaction with an advert that is related to the input property
Agent Indicates that a user interacted with their searchagent
InstantNotification Indicates that the user interacted with a notification that fired instantly
DailyNotification Indicates that the user interacted with a notification that fires on a daily basis
redirect/brokerUsing the RedirectToBroker, will return a RedirectAddress string. Caching or other means of saving this response, is strictly forbidden. The Partner must always use this endpoint to retrieve the data.
totalcountReturns the total number of searchable, active properties as an Integer (32-bit)
newcountReturns the number of searchable, active properties that have been uploaded since the start of request date, as an Integer (32-bit).
lastseenReturns a list of properties that were last seen by the user. The model is PropertyTeaser, with an additional property, LastSeen which is a datetime.
phoneTaking a propertyId as parameter, this will return a PhoneNumber string. Caching or other means of saving this response, is strictly forbidden. The Partner must always use this endpoint to retrieve the data.
mailTaking a propertyId as parameter, this will return an EmailAddress string. Caching or other means of saving this response, is strictly forbidden. The Partner must always use this endpoint to retrieve the data.
contactThis method is used, when a use wishes to get contacted by the broker. The input model looks as follows:
property type DescriptionName String The name of the userCompany String The company, for which the user
worksEmail String The email the user wishes to get
contacted onPhoneNumber String The phonenumber the user wishes
to get contacted onUserHasAcceptedTerms Boolean Indicates that the user has legally
accepted the terms and conditions that were provided by the Partner.
GET list/searchFilterIdTakes the id of the searchfilter, pageNumber (optional), sortorder (optional) and whether the ordering is descending (optional). Returns the following model:
Property type DescriptionTotalNumberOfResults Integer (32-bit) The number of total results that
match this searchfilter’s criteriaSearchFilterId Guid Used in case this filter needs to be
saved etcNumberOfPages Integer (32-bit) The number of total pages with the
input valuesCurrentPageNumber Integer (32-bit) The pagenumber this result
representsProperties Array of PropertyTeasers View the further documentation
PUT list/searchFilterIdTakes a searchfilter and its id as parameters and returns the same model as GET list/searchFilterId. The request model looks like this:
property type DescriptionDisplayOptions DisplayOptions View the further documentation
about displayoptionsSearchFilter SearchFilter View the further documentation
about searchfilters
DisplayOptionsproperty type DescriptionItemsPerPage Integer (32-bit) The number of properties that
should be shown per page. Should never exceed 100 and must be higher than 0.
PageNumber Integer(32-bit) The pagenumber to view which must be higher than 0.
SortByDescending Boolean Defines if the results should be ordered descending or ascending
SortOrder SortOrder View the sortorders in this document.
SearchFilterproperty type DescriptionPropertyType PropertyType View the propertytypes section in
this documentInterestType Array of InterestTypes View the interesttypes section in
this documentCategories Array of Categories View the categories section in this
documentSituations Array of situation View the situations section in this
document.Geometry RadiusSearchRequest RadiusSearchRequest contains a
Center with Latitude and Longitude as decimals. RadiusMetres is an integer.
SearchWords Array of searchword View the searchwords section in this document
Intervals Array of interval View the intervals section in this document.Each interval should also define a minimum and a maximum value. Each being Integet (32-bit) values.
GET list/searchFilterId/notificationIdTakes both a searchFilterId and a notificationId as parameters, and returns only the list of the properties from the specified notification.
GET map/searchFilterIdTakes a searchFilterId, and returns this model:
property type DescriptionPropertyMapPoints PropertyMapPoint Read on for further documentationSearchFilterId Guid The id of the search filterTotalNumberOfResults Integer (32-bit) The number of results in this output
PropertyMapPointProperty type DescriptionPropertyId Integer (32-bit) The id of the propertyLatitude Double Indicate the specific location of this
property.Longitude DoubleViewPropertyTeaserUrl String The url to use, when teaser
information is required
PUT map/searchFilterIdTakes the same request as PUT list/searchFilterId and responds as GET map/searchFilterId
PUT map/searchFilterId/notificationIdTakes the same request as PUT list/searchFilterId/notificationId and responds as GET map/searchFilterId.
POST listTakes the same searchFilter and display options as discussed earlier and returns a new searchfilterid with the same model as GET list/searchFilterId
POST mapTakes the same searchFilter and display options as discussed earlier and returns a new searchfilterid with the same model as GET map/searchFilterId
GET map/teaser/propertyIdMainly used for when a user interacts with a propertymap model. This model is found here
PUT map/regionalcountUsing the input searchFilterId and limitations, returns a list of the following model:
Property Type DescriptionGeoType String The type of situationGeoName String Name of the current situationNumberOfMatchingProperties Integer (32-bit) The number of properties that are
Property Type DescriptionSearchWordResults Array of SearchWordResult Read further for this modelDisplayWord String The word to displayNumberOfMatchingProperties Integer (32-bit) The number of properties that
contain the word(s)
SearchWordResultProperty type DescriptionWordId Integer (32-bit) The id that the API will use to better
identify the inputParentId Integer (32-bit) – nullable An Id of this word’s parent if anyeWordType String View this document for wordtypesWord String The word to search for
locationSearches for valid locations that can be put into the searchfilter. Uses the same requestmodel as “combined”
The response looking like this:
property type DescriptionGeoType String View the further documentation
about geotypesGeoName String The name of the locationNumberOfMatchingProperties Integer (32-bit) The number of properties that are
situated here
latestReturns a list of the latest SearchFilters
Property type DescriptionSearchFilterId String The id of the searchFilterLastSearchDate DateTime The date of the last time this filter
was usedPills List of strings An overview of which filters were
used
subscriptionsGET agentReturns a list of the user’s searchagents
POST agentCreates a new search agent and returns its base info.
DELETE agent/searchFilterIdDeletes the input search agent
POST agent/searchFilterIdCreates an agent with the searchFilterId
PUT agent/searchFilterId/settingsUsing the optional parameters, name, isMailAgent, isDailyPush and isInstantPush – updates the input searchAgent accordingly.
PUT agent/searchFilterId/nameUpdates the name on a search agent
DELETE agent/searchFilterId/nameDeletes the name on a search agent
GET agent/list/searchFilterIdReturns a list of properties, using the search agent’s filter. Optional Parameters: pageNumber, sortOrder, sortDescending.
GET agent/map/searchFilterIdReturns a list of properties, using the search agent’s filter
GET notification/notificationIdReturns a list of properties that match the input notification Id.
property Optional type DescriptionNotificationId False String The notificationId for which
the properties should match
GET inboxReturns a list of notifications for a registered user
GET inbox/countReturns the number of unread notifications for a user
PUT inbox/notificationIdUsing the input notificationId and the optional markAsRead parameter, this sets a notification as read by default.
PUT inbox/allMarks all notifications as read for the user.
usersThis section describes all methods that relates to users.
POST users/anonymousCreates an anonymous user and returns an Id of that user. This id should be used as the ETUser header where required.
GET users/informationReturns the name and e-mail for the input ETUser.
PUT users/informationUpdates the name and e-mail for the input ETUser.
DELETE users/loginDeletes any kind of user, using the input ETUser header.
POST users/loginPerforms a login, using the input credentials and returns this user’s id.
PUT users/login/changepasswordChanges the input user’s password
POST users/login/forgotpasswordSends an email, helping the user change the password.
POST users/login/creationCreates a new user with the input mail, password and name – then returns an Id.
GET users/devicetokenReturns a list of devicetokens.
POST users/devicetokenAdds the input devicetoken to the list for the input user.
ErrorcodesThis list is an overview of the possible error codes that are returned during validation. Multiple errors may exist on a request, but only one error will be returned at a time.
Here is a quick reference/overview of the codes:
ErrorCode interval Name1000-1999 Errors that have anything to do with the RequestHeaders2000-2999 Errors about the user3000-3999 Errors about a property