Hallo - API Developers Guide

Get Started

Today information is consumed at such a pace, across such a breadth of media that syndication of data, and the accessibility of that data has become even more important for users, businesses and developers. Hallo is one of the UK's leading classifieds websites and a growing platform for sales and outreach. We're now inviting developers to dive in new opportunities and make their products, properties and ads available quickly and easily.

To start using Hallo API, developers will require an API key. Such is available on request through the Profile Setting in your Hallo account. Keys are normally issued within 24 hours of request and subject to our Terms of Use.

The Basics

Hallo API supports json and xml formats in responce communication. The format can be specified through the optional .format parameter, and if this optional parameter is missed, the API will default results to json.

Every request is passed to method url together with parameters specific for the method, described below in this documentation.

Example Method URL:
https://api.hallo.co.uk/adverts/categories{.format}?key={key}

NOTE These default parameters will be excluded in method descriptions below, unless are the only parameters of the method.

---

Get Categories List

Returns information about the category tree.

Method URL (GET):
https://api.hallo.co.uk/adverts/categories{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Get Advert Details

Returns all available information for an advert.

Method URL (GET):
https://api.hallo.co.uk/adverts/{hallo_ref}{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Get Advert Specification

This method returns a template of all available fields for an advert based on category_id of posting. Adverts in different categories will require different set of details. The spec includes as well indication for required fields.

Method URL (GET):
https://api.hallo.co.uk/adverts/specification/{category_id}{.format}?key={key}

Response Fields
Field and requirements may vary depending on category and their type.

Get My Adverts List

Returns list of own adverts as per search parameters.

Method URL (GET):
https://api.hallo.co.uk/adverts/mylist{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Post Advert by XML / JSON

Posts a structured json or xml formatted stream for submission. For complete fields list and structure for specific category see Get Advert Specification.

Use preferred image upload method after advert ref is returned to upload image(s) associated to this advert.

Method URL (POST):
https://api.hallo.co.uk/adverts/add{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Post Advert by Form

Submits advert fields as Form elements or pair-value array. Upload form requires enctype="multipart/form-data". For complete fields list and structure for specific category see Get Advert Specification.

Use preferred image upload method after advert ref is returned to upload image(s) associated to this advert.

Method URL:
https://api.hallo.co.uk/adverts/request/add{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Delete Advert

Returns the heirarchy of the categories tree.

Method URL:
https://api.hallo.co.uk/adverts/remove/{hallo_ref}{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Index Search

Performs a search and returns summarised information about advert available on Hallo's live index.

Method URL:
https://api.hallo.co.uk/adverts/search{.format}?key={key}&par1=value&par2=value

Response Fields
List of fields returned by the request, excluding header fields.

Get My Images List

Returns list of my images.

Method URL:
https://api.hallo.co.uk/files/list{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Upload Image by Post

Upload image from Post request.

Method URL:
https://api.hallo.co.uk/files/post{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Upload Image from URL

Uploads an image, which is available on provided URL.

Method URL:
https://api.hallo.co.uk/files/post/url{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Delete Image

Deletes an image from "My Images" and removes association from adverts. Please note, if this is the default image, all other images will be removed as well.

Method URL:
https://api.hallo.co.uk/files/remove/{hallo_ref}{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

Link Image To Advert

Links an image from "My Images" to an existing advert.

Method URL:
https://api.hallo.co.uk/adverts/link/file{.format}?key={key}&hallo_ref=value&file_id=value

Response Fields
List of fields returned by the request, excluding header fields.

Get My Profile Settings

Returns some user profile settings.

Method URL:
https://api.hallo.co.uk/user/details{.format}?key={key}

Response Fields
List of fields returned by the request, excluding header fields.

---

Import Tool for CSV & Excel

For bulk upload of products, properties and jobs, an import tool is available from My Adverts section in your Hallo account.

A benefit of the the tool is that it allows only certian fields to be imported by selecting the source columns from an existing source file. Some fields will be picked directly from the user's profile (like contact details) and others can be prefilled on screen with particular for the import preferences.

Although is the quickest solution for bulk upload we can think of, this import tool does not allow upload of images, so they have to be uploaded after the import.

The import makes use of the "external_ref" field, which the user can submit as their own reference number for the classifieds listing. Adverts re-posted later with the same "external_ref" code, will updated and bumped-up, instead of being duplicated.

All new adverts imported by the tool will be first held under review with status message showing in your adverts list as "108 Imported Product Waiting Approval". Once an advert is approved and "external_ref" is matched on next import, the advert will be released without moderation.

---

API Terms of Use

This API is available under following terms, which extend Hallo's main Terms & Conditions and our Advertising Guidelines.

Thank you for using the Hallo API.

This API is owned and operated by Increate Ltd under the trading names of “Hallo”, “Hallo UK”, “Hallo.co.uk” or in the contents of these terms as “We” and Registered in England and Wales under company number 05965686 with registered address is 125 Claremont Road, NW2 1AH, London.

By accessing and using the Hallo API (the "API"), you or the identity you represent (the “3rd party”, “you”) explicitly agree to comply with and be bound by the following Terms and Conditions (“Terms”, “Terms of Use”, “Terms and Conditions”, “Agreement”), which We reserve the right to change at any time, with or without notice, in our sole and absolute discretion. Please, make sure that you regularly make yourself familiar with the current terms of use and you are conforming to the most recent version of these terms.

1. The Content

The API is a service that offers content programming tools, enabling third parties to create applications or websites that display certain content (“the Content”) that “Hallo” offer by way of output from the API and update from time to time, subject to these Terms. The Content includes, but is not limited to, the output of the API methods as listed in each of the sections of the API Documentation, located at https://www.hallo.co.uk/api_docs, including agent property listings and proprietary data around property values.

2. Access To The API

Access to the API is subject to approval by “Hallo” and a developer key which is required to be able to make calls to the API and retrieve the content. You may only access the Content using a single and unique key supplied by “Hallo” as an approved licensee. It is possible that you are required to apply for separate keys in order to access the Content from different API methods. The key is confidential and neither the key nor the Content may be sold, leased, transferred or sublicensed to any other party whether for commercial or person purpose, without written permission from "Hallo".

By making use of the API, you agree to “Hallo” accessing your application and/or other materials related to your use of the API as reasonably requested by us to verify your compliance with these Terms. You agree that we may crawl or monitor applications using Content from “Hallo” and you agree not to block or interfere with such efforts.

Every new key is initially issued under a three month free license. This enables “Hallo” to review our basic terms of use are in effect or follow up cases where additional terms need to be agreed. Although each key is limited to 200 calls per hour, we're happy to hear why you need more so email us on . "Hallo" may approve higher daily call limits at our own discretion or may enforce lower daily limits if necessary.

3. Use of Content

The API cannot be used to disintermediate standard “Hallo” business practices. For example, you cannot use “Hallo” Content as a standalone method of generating appraisal commercial leads to without there being commercial benefit to “Hallo”, either in the form of a pre-agreed commercial licence of the appropriate API calls to facilitate this, or through an affiliate commission model whereby the application is providing additional reach for “Hallo” lead generation. We will disable any API key related to applications that contravene this clause with immediate effect.

If the web address or application cannot be viewed publicly, a test environment or screengrabs will need to be provided unless specific approval has been given otherwise. If you are unable to demonstrate how you are using “Hallo” data we will be forced to disable the key until such time that you can. To request approval in such instances, please contact . 

4. Displaying the Content

Any Content delivered by “Hallo” channels including this API, cannot be re-distributed at any time without requesting written permission from “Hallo”.

The raw output from any API method cannot be modified by the 3rd party without prior permission. This does not include re-styling from the perspective of colour & font.

You may not retain any copies of the “Hallo” API output data. Your license to “Hallo” data via the API is limited to displaying classifieds ads and directing the user to the “Hallo” site from which the user can view the complete data on “Hallo.co.uk” or to contact the relevant supplier of the information via “Hallo.co.uk”.
You must not use the API Content to offer or promote services that compete with “Hallo”.

Content from this API output cannot be used to send leads or traffic directly to suppliers and users of “Hallo”, but must direct only to “Hallo.co.uk”.
“Hallo.co.uk” reserves the right, without notice and in our sole discretion, to terminate the 3rd party’s API license and give immediate notice to the 3rd party to destroy all versions of the API data on the 3rd parties application or website. For example, if the content of your website or application is of an offensive or unsavoury nature, or if the "Hallo" data is published in an a manner or context that could, in our reasonable opinion, cause harm to our goodwill, conflict with our values and the objectives of our paying customers or bring our brand into disrepute, we will disable the relevant API key(s).

In the instance of the listings API, unless we have given immediate notice on usage of the content and have terminated the API license and access, the 3rd party is allowed to maintain a listing without it being updated, for 72 hours, in the instance of technical complications with the output. Where updated content is available (usually daily), the 3rd party is obliged to replace the previous listing with the new listing data.

In cases where listings are on a 3rd party website, the content must link through to the original listing page on “Hallo” and it is the 3rd party's responsibility to implement the “nofollow” HTML attribute to content and on these links.

In addition to a link back to the original content, any references to "Hallo" content as obtained via the API must include a link or reference with text "Powered by Hallo.co.uk".

Listings  must be accompanied by "Marketed by" data I.e agent name, logo and phone number. API developers are not permitted to publish or pass off any advertisement assets whether current or expired, without the expressed permission of the listing agent and provided in writing to api@zpg.co.uk

You may not use the Hallo API content for any offline marketing without crediting “Hallo UK” and in accordance with our general attribution rules.

You agree not to use “Hallo” Content or branding in any way that is unlawful, or harms “Hallo”, its service providers, its agents, suppliers, your end users, or any other person. Hallo reserve the right to revoke you license to use the Hallo API, Hallo Data and Hallo Brand if and when Hallo deem your usage to be damaging or inappropriate.

5. Limited Relationship

Nothing within these terms should constitute relationship, partnership, or a joint venture between “Hallo” and the 3rd party. You may publicly refer to your use of our API, but you agree not make any other public statements that assert or imply any other relationship with “Hallo”, unless our prior written approval.

6. Indemnity

You agree to hold harmless and indemnify “Hallo”, its subsidiaries, affiliates, officers, agents, employees, and suppliers, from and against any 3rd party claim arising from or in any way related to your or your users' use of the “Hallo” API or “Hallo” data, use of “Hallo” brand & links other than as set out in the “Hallo” documentation and guidelines.  Violation of these Terms other actions connected with use of “Hallo” services, including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, “Hallo” will provide you with written notice of such claim, suit or action.

7. No warranties

This API including the content and service (including reliability) are provided on an as is basis without any warranties either explicit or implicit. You expressly agree that the use of this site and the API, including all content or data distribute by or downloaded from the service, is at your sole risk. We disclaim all warranties, explicit or implicit, including but not limited to implied warranties or merchantability fitness for a particular purpose, title and non-infringement as to the information, materials, and content on the site. We do not represent or warrant that materials in this site are accurate, complete, reliable, current, or error-free.

8. Liability limitation

In no event shall Increate Ltd t/a “Hallo”, its officers, directors, agents, partners, employees, advertisers, or data providers be liable for any indirect, special , incidental, consequential or punitive damages (including but not limited to loss of use, loss of profits, or loss of data) whether in an action in contract, tort, (including but not limited to negligence), equity or otherwise, arising out of or in any way connected with the use of the “Hallo” API or “Hallo” data or services. Some jurisdictions do not allow the exclusion or limitation of liability so the above limitations may not apply to you.

Version Log

Latest version of the API is [1.0]. History of changes can be found in list below.

• Version 1.0 Change Log:
  • Methods Added:
    • Get Categories List
      
    • Get Advert Details
      
    • Get Advert Specification
      
    • Get My Adverts
      
    • Post Advert by JSON / XML
      
    • Post Advert by Form
      
    • Delete Advert
      
    • Index Search
      
    • Get My Images List
      
    • Upload Image by Post
      
    • Upload Image by URL
      
    • Delete Image
      
    • Get My Profile Details