Using /vocabularies and /places

Map your values to ours once, store the mapping in your software, and refresh it when the vocabulary version changes. Neither endpoint takes a connection.

GET /vocabularies#

GET /api/partners/v1/vocabularies

200 { "version": "sha256:…", "categories": [ … ], "transaction": [ … ], "heating": [ … ], "condition": [ … ], "furnished": [ … ],
      "building_group": [ … ], "ownership_status": [ … ], "legalization_status": [ … ], "rental_type": [ … ], "room_types": [ … ],
      "amenities": [ … ], "remove_reasons": [ … ], "attributes_by_category": { … } }

• Every enumeration the payload uses, with English and Serbian labels, and the per-category attributes schema.
• It is generated from the same constants the agency editor uses, so a new value appears in the API in the same release as in the editor.
• version is a SHA-256 of the whole document. The response carries an ETag; send it back as If-None-Match and an unchanged document answers 304 with no body.
• Stability: additive changes (a new value) keep v1 and are listed in the changelog. Removing a value is a breaking change and ships as a new version.

Reference: GET /vocabularies.

GET /places#

Search our cities and municipalities:

GET /api/partners/v1/places?q=Vra%C4%8Dar&type=municipality

200 { "places": [ { "id": "b2c0…", "type": "municipality", "name_sr": "Vračar", "name_en": "Vračar", "official_code": "70114",
      "city_id": "…", "city_name_sr": "Beograd", "lat": 44.80, "lng": 20.48 } ], "next_cursor": null }

• q matches Latin, Cyrillic and English names (any part of the name, upper or lower case) and the official code (official_code, the national register code, exactly). Vračar, vračar, Врачар and its official code find the same place.
• The diacritics must match: the search does not fold č, ć, š, ž or đ, so vracar finds nothing. URL-encode the query as UTF-8 (Vra%C4%8Dar). If your software stores names without diacritics, search by the Cyrillic name or the official code, or keep your own mapping to our place ids.
• type is city or municipality.
• Page with cursor and limit (1–200) until next_cursor is null.

Reference: GET /places.

GET /places/{id}#

GET /api/partners/v1/places/b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d

200 { "place": { … } }, or 404 place_not_found. Reference: GET /places/{id}.

Using a place#

Put the place's id in location.place_id. Send the most specific place you know: a municipality implies its city. An id we don't know is refused with unknown_place at /location/place_id (in a batch, the item is rejected with geo_unresolved). Neighbourhoods are free text in location.neighbourhood; there is no neighbourhood list.