Taxonomy for locations

❗️Only for Otodom

Coordinates are the preferred way to integrate with our location service via OLX RE API, but unfortunately, we are facing a few issues with wrong mapping and algorithms to translate the coordinates into location names. For this reason, we created a temporary solution to mitigate these issues.

Coordinates will always be mandatory, but you can also send us custom fields with IDs of a few levels of locations.

The flow should be:

Create your dataset (we have it available in two formats: JSON and SQL. Ask us for the data)
or query our location search services to get location IDs during advert creation/update.
Use Location custom fields in the advert payload to send the Location IDs + coordinates

Location Search

The address endpoint structure is:

		cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--header 'User-Agent: '

Copied to clipboard

The path is mandatory. Available endpoint paths:

Path	Description
/regions	IDs for the Polish Regions
/subregions	IDs for the Polish Subregions
/cities	IDs for the Polish Cities
/districts	IDs for the Polish Districts. Not all Cities have Districts.

You can also specify query parameters. Take a look below:

Parameter	Description
offset	Type: numeric (number) Specifies the offset (how many elements to skip)
limit	Type: numeric (number) Specifies the limit (to how many items to limit the results)
children	Type: logical (boolean) Set 'true' it shows the child elements (if available). Pagination is also available here.
id	Type: numeric (number) Returns only elements with the given ID.
search	Type: string Returns all elements with the given substring.

Some examples:

Getting the city with the ID number: 213:

		cURL

cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/cities?id=213' \

Copied to clipboard

Getting the city with the ID number: 213 with subordinate elements (districts), the number of elements is limited to 100:

		cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/cities?id=213&children=true&limit=100' \

Copied to clipboard

Getting the city with the ID number: 213 with subordinate elements (districts), the number of elements is limited to 100, omitting the first 30 elements:

		cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/cities?id=213&children=true&limit=100&offset=30' \

Copied to clipboard

Search for multiple levels

In order to have search for multiple levels simultaneously, you can use the multi level search endpoint.

The address endpoint structure is:

		cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/search?regions=X&subregions=Y&cities=Z' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--header 'User-Agent: '

Copied to clipboard

With the following rules:

the params regions, subregions, and cities are required to avoid returning too many results.
the param districts is optional. If omitted, it will display all children districts of the cities that match with the query
the query is made with all params considered (AND operations).

Example:

		cURL

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/search?regions=dolnośląskie&subregions=Wrocław&cities=Wrocław' \

Copied to clipboard

Which will return:

		JSON

{
  "meta": {
    "count_cities": 1,
    "count_districts": 1,
    "count_regions": 1,
    "count_subregions": 1,
    "status_code": 200,
    "transaction_id": "202d252c-fd70-4c37-9908-6382fae42358"
  },
  "data": [
    {
      "id": 1,
      "code": "dolnoslaskie",
      "name": "dolnośląskie",
      "subregions": [
        {
          "id": 381,
          "region_id": 0,
          "code": "powiat-wroclaw",
          "name": "Wrocław",
          "cities": [
            {
              "id": 39,
              "subregion_id": 0,
              "code": "wroclaw",
              "name": "Wrocław",
              "districts": [
                {
                  "id": 4,
                  "city_id": 0,
                  "code": "psie-pole",
                  "name": "Psie Pole"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Copied to clipboard

Search for one level

To obtain the location id for a certain city or region, you need to execute the following request:

		JSON

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/cities?id=213

Copied to clipboard

Change the path for any of the available ones, also instead of id, you can use the name of the location level using the parameter search.

Search Pagination

You only need to set the parameter limit to the exact number you want to use pagination. You can use the pagination limit to avoid returning too many results.
Example:

		JSON

curl --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/regions?limit=100

Copied to clipboard

When making this request, you'll get 100 results per page. To get the following 100 results, you should get the available link in the link object of the response. You'll also find a link to the first page in this object. If there are no results, the links object will be omitted.

Location custom fields

When you send the advert to the RE Partner API, under location object (under data), you can add an extra object called "custom_fields".
Inside, you can specify the "city_id" or the "district_id" that you got from the Location search. Also, we will enable the option to send "street_name" and "quarter_name" as strings.

Here's the example:

		JSON

{
  "location": {
    "lat": 101010101, // mandatory
    "lon": 101010101, // mandatory
    "exact": false, // optional, if set to true we display the street name (if sent)
    "custom_fields": { // optional
      "city_id": 12, // either city_id OR district_id
      "district_id": 12, // either city_id OR district_id
      "quarter_name": "LoremIpsum", 
      "street_name": "LoremIpsum",
      ...
    }
  }
}

Copied to clipboard

As you can see in the example above, the coordinates are still mandatory because we will fall back to coordinates if we don't have the location ids. The entire custom_fields block is optional, and you can send the city_id/district_id and/or quarter_name and/or street_name. We accept strings for quarter and street names since we store exactly what you will send in the database.

Location notification

Event flow name: publish_advert
This flow group events related to advert publish operations. For each operation/request made, there's a success and an error event. For each event, you will find the code of the advert. These codes represent the status of the advert on the target site. See more on Advert status codes.

When something is wrong with your request, related only to the location ids, the advert can be successfully posted, you will get the notification flow from event_type advert_posted_success and a warning message to inform you that the location id does not exist, from event_type advert_location_error.

If the district is wrong, you will receive a notification like the one below, in our callback notification.

		JSON

{
  "destination": "",
  "timestamp": 1646420591327,
  "event_timestamp": 1646420591327,
  "transaction_id": "e783c8a2-4adb-476b-88dd-218fbb24d8e5",
  "object_id": "da9b2722-13e6-4cd9-8112-7106f7e6ddf3",
  "flow": "publish_advert",
  "error_message": "Invalid district id: 12",
  "data": {
    "detail": "Invalid district id: 12",
    "title": "Invalid location.",
    "validation": [
      {
        "detail": "Invalid district id: 12",
        "field": "district_id",
        "title": "Invalid location."
      }
    ]
  },
  "event_type": "advert_location_error"
}

Copied to clipboard