Use the API
This submission method is designed for software professionals who understand the HTTP protocol. If you do not, you will be better served by our CSV or form-based submission methods.
You may submit properties to OnOneMap using HTTP GET or POST requests. Each request represents one property to be added, and the server will return an XML response. The requests should be sent to the following URL:
http://ononemap.com/lib/ajx/api
The following variables can be provided, in any order, either by GET or POST:
| Variable name | Description | Constraints | Example |
|---|---|---|---|
| action | [Required] Always set to 'add'. We will be providing additional API features in the future. | "add" only | "add" |
| sourceid | If your have an OnOneMap sourceid, provide it here. In conjunction with the siteref, this allows us to correlate this property with your previous submissions, and also allows yout to place a named credit against your links. If you do not provide a sourceid, your properties will be grouped by domain. Get one now... |
numeric | 1234 |
| siteref | A unique identifier of your choice for this property within your own data set. Ignored unless sourceid is also provided. The two together allow us to identify the difference between a new property and an update to an existing one. | 0-25 char | AT563/2 |
| title | [Required] The headline of the property particulars. We'd prefer this to be a road name or property/building name. | 5-30 char | "Bristol Avenue", "Argrove Mansions", "Lakefield House" |
| numbeds | [Required] The number of bedrooms in the property. If it's a studio, set to 0, but it has to be a number. | numeric | 2 |
| address | A more general description of the area in which the property is located. Does not have to be a full address. Please do not repeat the information entered in 'title'. | 0-50 char | "Twickenham, Middlesex" |
| postcode | [Critical] Enter the full postcode of the property. This is essential to enable us to plot it correctly on the map. Must match the following regex: /^(((([A-PR-UWYZ][0-9][0-9A-HJKS-UW]?)| ([A-PR-UWYZ][A-HK-Y][0-9][0-9ABEHMNPRV-Y]?)) s{0,2}[0-9]([ABD-HJLNP-UW-Z]{2}))|(GIRs{0,2} 0AA))$/ | 8 char | TW1 0AA |
| proptype | [Required] We only recognise two different types of property, so please set this to 'house' or 'flat', depending only on whether there are several properties occupying the same freehold. | "house" or "flat" only | "house" |
| price | [Required] Set the price of the property as a number, in pounds sterling. If this is a lettings submission, set the rent in pounds per calendar month (even if the rent is normally charged weekly). | numeric | 267950 |
| contactname | Set the name of the person or agency branch that should be contacted for more details about the property. | 50 char | "My Agency Twickenham Branch" |
| phone | Set the phone number of the person or office named in the previous column. Use only numbers and spaces, and pay attention to the correct spacing of phone numbers in your area - for example London is 020 XXXX XXXX, not 020X XXX XXXX. | 25 char | "020 0000 0000" |
| link | [Required] Set a full URL of the specific page on which a person can view the particulars of this property. Must match the following regex: /^http://(([0-9]{1,3}.){3}[0-9]{1,3}|([0-9a-z-]+.)+[a-z]{2,6})(:[0-9]+)?/ | 255 char | "http://www.example.com/prop12345.html" |
| imgurl | Set a full URL of an image showing the property. The image should be approx 100x70 pixels if possible (it will be forced to occupy a frame of those dimensions). Must match the following regex: /^http://(([0-9]{1,3}.){3}[0-9]{1,3}|([0-9a-z-]+.)+[a-z]{2,6})(:[0-9]+)?/ | 255 char | "http://www.example.com/images/12345.jpg" |
| description | Optional full description of the property. Not currently used but we will allow people to search this in the near future. | 30,000 char | "Spacious modern family home...." |
| type | [Required] Set to either "Sales" or "Rentals" depending on whether the property is a letting or sale. If the property is for rent, the price field should specify the rent in pounds per calendar month. | "Sales" or "Rentals" only | Sales |
| lat | Although you must provide the postcode of the property, you can if you wish provide a specific location at which to plot the property, as long as that location is within the accompanying postcode. This is the most accurate means of ensuring the property is plotted in the right place. | numeric, in range 49 to 61 | 51.4467329 |
| lng | See lat. | numeric, in range -8 to 2 | -0.32709232 |
| os_x | Although you must provide the postcode of the property, you can if you wish provide a specific location at which to plot the property, as long as that location is within the accompanying postcode. As with the lat/long option, this is an optional way of providing a more accurate location for the property using Ordanance Survey 6 figure grid references. | numeric, in range 30000 to 670000 | 274522 |
| os_y | See os_x. | numeric, in range 10000 to 1220000 | 274522 |
| receiptto | Whilst you will get an immediate rejection from the API if your submitted property data is invalid or incomplete, there are other reasons that we might reject individual properties that won't be tested until the property is loaded into our main index, which happens overnight. If you want all your submissions receipted to an email address, provide it here. You will receive a daily digest of the procesisng results of each submission you make, including any late rejections of properties that were accepted by the API. Must match the regex /^[A-z0-9][\w\.\-\+]*@[A-z0-9][\w\-\.]+\.[A-z0-9]{2,6}$/i |
100 char | joe.bloggs@example.com |
All the above variables should be URL encoded, and if sending using GET, be aware of the 255-character limit loosely enforced in the HTTP specification (we recommend that you POST).
Response
If the submission is accepted, the following response will be received from the server:
<results requestedaction="add">
<submission response="OK" id="XXXXXXX" />
</results>
The ID number returned is a queue ID that allows the property to be found in the indexing queue. It should currently be retained only for queries relating to the submission, but in future may be required to access additional property-specific API functions.
If the submission fails the following response will be received:
<results requestedaction="add">
<error type="incomplete" fieldname="title" />
<error type="invalid" fieldname="price" />
<error type="invalid" fieldname="imgurl" />
</results>
Each <error> element represents one problem with a single field. Incomplete fields are those that are required but which you have not supplied, or for which you have not provided a long enough string. Invalid fields have failed to pass validation checks, and so you should recheck the defintion of the field to ensure that you have provided valid data.
It is important to note that the invalid error will also be generated if you supply invalid data in an optional field. You could therefore resolve these kinds of errors by removing the invalid data from the submission - you don't necessarily have to correct it.