❗️

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:

1. 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.
2. Use Location custom fields in the advert payload to send the Location IDs + coordinates

Location Search

The address endpoint structure is:

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

The path is mandatory. Available endpoint paths:

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

Some examples:

1. Getting the city with the ID number: 213:

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

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

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

3. 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 --location --request GET 'https://api.olxgroup.com/locations/v1/urn:site:otodompl/cities?id=213&children=true&limit=100&offset=30' \

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 --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: <YOUR API KEY>' \
--header 'User-Agent: <YOUR CRM NAME>'

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 that of the cities that match with the query
• the query is made with all params considered (AND operations).

Example:

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

Which will return:

{
  "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"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Search for one level

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

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

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:

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

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.

📘

On the request, no need to send all the locations IDs. You need to send the lowest level you want—no need to send subregion_id and region_id.

Here's the example:

{
  "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",
      ...
    }
  }
}

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.

{
  "destination": "<your callback notification>",
  "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"
}