Zoddak - api

API v1 (Application Programming Interface)

This API provides information about real estate developments, their locations, stages, and details. Responses are returned in JSON

{
  "status": 200,
  "content": "OK",
  "sandbox": False,
  "total_items": ...,
  ...
}

All routes return the following header:

Content-Type: application/json

The testing environment is accessed by appending /sandbox to the endpoint URL after enabling the feature on our platform.

This environment supports a maximum of three promotions, english description only, three images, and three units.

The documentation is not available in the feed, the API or the wordpress plugin, these services are designed to show information about new developments on your website to your end customers. Their main objective is to generate interest and capture the attention of potential customers, encouraging them to contact your agency. It is not intended to provide all the project documentation.

In many cases, the documents provided by the marketers or developers contain detailed information, including text and graphics, which could lead a customer to go directly to the sales office without first contacting your agency. Therefore, we want to ensure that the agency is the primary point of contact for potential buyers.

Endpoints

1. `GET /locations`

Description: Ordered list of cities with ordered lists of areas that have active promotions.

Response:

<!-- https://api.zoddak.com/v1/locations -->
{
  "status": 200,
  "content": "OK",
  "total_items": 2,
  "locations": [
    {
      "town": "Town A",
      "places": ["Center", "North"]
    },
    {
      "town": "Town B",
      "places": ["Beach"]
    }
  ]
}

2. `GET /stages`

Description: Returns the different statuses/stages of developments in multiple languages.

Languages: es (Spanish), en (English), da (Danish), de (German), fr (French), nl (Dutch), no (Norwegian), fi (Finnish), ru (Russian), sv (Swedish), ro (Romanian).

Stages: Coming soon, Offplan, With licence, Started, Completed.

Response:

<!-- https://api.zoddak.com/v1/stages -->
{
  "status": 200,
  "content": "OK",
  "total_items": 5,
  "stages": [
    {
      "id": 1,
      "en": "Under construction",
      "es": "En construcción",
      "fr": "En construction",
      ...
    }
  ]
}

3. `GET /developments`

Retrieve information about one or multiple developments with pagination and filters.

Parameters

Path / Argument:
- 'ref_id' (string or int, optional) → reference or ID of the development.
Query Params:
- 'lan' (string, optional, default: 'en') → language ('en', 'es', 'fr', etc.).
- 'npics' (int, optional, default: 1, max: 3) → number of images per development, if a single development is requested, all its images will be sent, for multiple developments, a maximum of 3 images per development will be returned.
- 'start' (int, optional, default: 0) → pagination start.
- 'end' (int, optional, default: 20) → pagination end. If not sent, 20 developments will be returned from 'start'.
- 'towns' (comma-separated list) → filter by towns.
- 'places' (comma-separated list) → filter by places.
- 'prop_types' (comma-separated list) → filter by property type. Apartments, Villas, Townhouses.
- 'min_price', 'max_price' (int, optionals) → price range.
- 'min_beds', 'max_beds' (int, optionals) → bedrooms range.
- 'min_baths', 'max_baths' (int, optionals) → bathrooms range.
- 'orderby' (string, optional) → field to order by 'town', 'place', 'prop_type', 'min_price', 'max_price', 'min_beds', 'max_beds'.
- 'stages' (comma-separated list of int, optional) → filter by stage/status.

Examples

Specific development (by ID):
```
GET /developments/295
```
Specific development (by reference):
```
GET /developments/CHL
```

List with filters and pagination:

GET /developments?prop_types=villas,townhouses&start=0&end=10

GET /developments?towns=marbella,estepona&stages=4,5&min_price=800000&max_price=950000&min_beds=4&start=0&end=10

GET /developments?prop_types=villas&towns=marbella&stages=5&min_price=990000&min_beds=5&start=0&end=10

These requests are equivalent:

GET /developments

GET /developments?start=0&lan=en

GET /developments?start=0&end=20&lan=en

Response (single development by reference):

<!-- https://api.zoddak.com/v1/developments/CHL -->
{
  'status': 200,
  'content': 'OK',
  'metadata': {
    'id': 0,
    'ref': 'CHL'
  },
  'development': {
    'id': 295,
    'name': 'Cerrado Hills',
    'reference': 'CHL',
    'min_price': 2300240,
    'max_price': 2321640,
    'min_beds': 5,
    'max_beds': 5,
    'min_baths': 5,
    'max_baths': 5,
    'min_built_area': 357,
    'max_built_area': 399,
    'min_plot_area': 1157,
    'max_plot_area': 1174,
    'min_covered_terrace': 0,
    'max_covered_terrace': 0,
    'prop_type': 'Villas',
    'town': 'Mijas Costa',
    'place': 'Cerrado del Águila',
    'postcode': '29649',
    'last_update': '2025-09-12 13:31:32',
    'latitude': '36.5262408',
    'longitude': '-4.6686124',
    'price_title': 'From',
    'start_date': '',
    'completion_date': '18 months after the purchase of the plot',
    'description': '<div align="justify">
    A new luxury development of just 13 superb villas, each offering four en-suite bedrooms. These amazing villas are generous in size and quality.<br><br>

    Three of the bedrooms are located on the upper floor of the property, while another is adjacent to the living area. A large basement gives you the chance to modify the space to suit your needs; another bedroom, cinema room, wine cellar, gym...<br><br>

    The properties are positioned such that they arc around one of the greens of the Cerrado de Aguila golf course. This also means you have spectacular panoramic views of the Costa del Sol.<br><br>

    The luxurious open-plan living are is designed to facilitate daily life as well as entertaining. The kitchen, dining area and living room are all connected on one level to give you easy access and open areas from which to enjoy your views.<br><br>

    The bathrooms and kitchens are fitted only with high quality products from leading, luxury European manufacturers. The properties are also fitted with VTouch Pro allowing you to control many aspects of your home with the swipe of a finger. Lights, blinds, security, heating and A/C can all be controlled using an app on your mobile phone, or directly via the VTouch panel.
    </div>',
    'stage': 'Offplan',
    'units_total': 13,
    'units_available': 5,
    'units_sold': 8,
    'units': [
      {
        'block': '',
        'floor': '',
        'door': '',
        'unit': '19',
        'beds': 5,
        'baths': 5,
        'toilets': 0,
        'built_area': 399,
        'useful_area': 0,
        'covered_terrace': 0,
        'outdoor_terrace': 568,
        'solarium': 0,
        'basement': 0,
        'plot': 1166,
        'garden': 281,
        'common_areas': 0,
        'garage': 0,
        'storage_room': 0,
        'price': 2300240
      },
      {
        ...
      },
      {
        ...
      },
      {
        ...
      },
      {
        ...
      },
    ],
    'images_sm': [
      'https://api.zoddak.com/default/images/dev_pics.pic.bd2a6cc2b7d1e093.7069635f312e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.90b6638b5f6937a9.7069635f322e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.890205042e291ea9.7069635f332e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a0c030e86dde857d.7069635f342e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.b0ad739e6bb1c87f.7069635f352e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a4cc8b08f78b7066.7069635f362e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.aeb8ed244e3d415e.7069635f372e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8b9910f95e90e14d.7069635f382e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8ea018dcdaa097fb.7069635f392e6a7067_sm.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.9882acd5c3b6ac60.7069635f31302e6a7067_sm.jpg',
      ...
    ],
    'images_md': [
      'https://api.zoddak.com/default/images/dev_pics.pic.bd2a6cc2b7d1e093.7069635f312e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.90b6638b5f6937a9.7069635f322e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.890205042e291ea9.7069635f332e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a0c030e86dde857d.7069635f342e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.b0ad739e6bb1c87f.7069635f352e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a4cc8b08f78b7066.7069635f362e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.aeb8ed244e3d415e.7069635f372e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8b9910f95e90e14d.7069635f382e6a7067_md.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8ea018dcdaa097fb.7069635f392e6a7067_md.jpg',
      ...
    ],
    'images_lg': [
      'https://api.zoddak.com/default/images/dev_pics.pic.bd2a6cc2b7d1e093.7069635f312e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.90b6638b5f6937a9.7069635f322e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.890205042e291ea9.7069635f332e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a0c030e86dde857d.7069635f342e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.b0ad739e6bb1c87f.7069635f352e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.a4cc8b08f78b7066.7069635f362e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.aeb8ed244e3d415e.7069635f372e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8b9910f95e90e14d.7069635f382e6a7067_lg.jpg',
      'https://api.zoddak.com/default/images/dev_pics.pic.8ea018dcdaa097fb.7069635f392e6a7067_lg.jpg',
      ...
    ]
  }
}

Response (multiple developments):

<!-- https://api.zoddak.com/v1/developments?min_beds=5&min_price=1000000&towns=marbella -->
{
  'status': 200,
  'content': 'OK',
  'metadata': {
    'pagination': {
      'start': 0,
      'end': 20
    },
    'filters': {
      'towns': [
        'Marbella'
      ],
      'min_beds': 5
    }
  },
  'total_items': 39,
  'developments': [
    {
      'id': 295,
      'name': 'Cerrado Hills',
      'reference': 'CHL',
      'min_price': 2300240,
      'max_price': 2321640,
      'min_beds': 5,
      'max_beds': 5,
      'min_baths': 5,
      'max_baths': 5,
      'min_built_area': 357,
      'max_built_area': 399,
      'min_plot_area': 1157,
      'max_plot_area': 1174,
      'min_covered_terrace': 0,
      'max_covered_terrace': 0,
      'prop_type': 'Villas',
      'town': 'Mijas Costa',
      'place': 'Cerrado del Águila',
      'postcode': '29649',
      'last_update': '2025-09-12 13:31:32',
      'latitude': '36.5262408',
      'longitude': '-4.6686124',
      'price_title': 'From',
      'stage': 'Offplan',
      'units_available': 6,
    },
    {
      'id': ...
    },
    ...
  ]
}

Common Errors

400 Bad Request → Invalid parameters or query error.
401 Invalid or missing credentials → The request lacks valid authentication credentials.
401 No valid credentials → The authentication token provided is not recognized or is invalid.
403 No valid subscription → The API key used does not have an active subscription.
403 No ip whitelist in database → Your API key requires an IP whitelist, but none is configured.
403 IP %s not in whitelist → Your IP address is not included in the whitelist for this API key.
429 Maximum downloads reached (3) → You have exceeded the maximum allowed downloads. This limit applies only to the feed.
200 OK but 'total_items=0' → No developments found with the applied filters.

Token Authentication