{"id":758,"date":"2024-01-09T12:25:24","date_gmt":"2024-01-09T12:25:24","guid":{"rendered":"https:\/\/olxdoc.wpenginepowered.com\/?p=758"},"modified":"2024-01-29T15:03:17","modified_gmt":"2024-01-29T15:03:17","slug":"taxonomy-for-locations","status":"publish","type":"post","link":"https:\/\/doc.olxgroup.com\/api\/?p=758","title":{"rendered":"Taxonomy for locations"},"content":{"rendered":"\r\n<h1>Taxonomy for locations<\/h1>\r\n<p>\u2757\ufe0f<strong>Only for Otodom<\/strong> 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 <strong>temporary<\/strong>\u00a0solution 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.<\/p>\r\n<p>The flow should be:<\/p>\r\n<ol>\r\n<li>Create your dataset (we have it available in two formats: JSON and SQL. Ask us for the data)<br \/>or query our location search services to get location IDs during advert creation\/update.<\/li>\r\n<li>Use\u00a0<strong>Location custom fields<\/strong>\u00a0in the advert payload to send the Location IDs + coordinates<\/li>\r\n<\/ol>\r\n<p>Location Search<\/p>\r\n<p>The address endpoint structure is:<\/p>\r\n<p><code>cURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/' \r\n--header 'Accept: application\/json' \r\n--header 'Content-Type: application\/json' \r\n--header 'X-API-KEY: ' \r\n--header 'User-Agent: '<\/code><button>Copy<\/button> cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/&#8217; &#8211;header &#8216;Accept: application\/json&#8217; &#8211;header &#8216;Content-Type: application\/json&#8217; &#8211;header &#8216;X-API-KEY: &#8216; &#8211;header &#8216;User-Agent: &#8216; Copied to clipboard<\/p>\r\n<p>The path is mandatory. Available endpoint paths:<\/p>\r\n<table>\r\n<thead>\r\n<tr>\r\n<th>Path<\/th>\r\n<th>Description<\/th>\r\n<\/tr>\r\n<\/thead>\r\n<tbody>\r\n<tr>\r\n<td>\/regions<\/td>\r\n<td>IDs for the Polish Regions<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>\/subregions<\/td>\r\n<td>IDs for the Polish Subregions<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>\/cities<\/td>\r\n<td>IDs for the Polish Cities<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>\/districts<\/td>\r\n<td>IDs for the Polish Districts. Not all Cities have Districts.<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n<p>You can also specify query parameters. Take a look below:<\/p>\r\n<table>\r\n<thead>\r\n<tr>\r\n<th>Parameter<\/th>\r\n<th>Description<\/th>\r\n<\/tr>\r\n<\/thead>\r\n<tbody>\r\n<tr>\r\n<td>offset<\/td>\r\n<td>Type: numeric (number)<br \/>Specifies the offset (how many elements to skip)<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>limit<\/td>\r\n<td>Type: numeric (number)<br \/>Specifies the limit (to how many items to limit the results)<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>children<\/td>\r\n<td>Type: logical (boolean)<br \/>Set &#8216;true&#8217; it shows the child elements (if available). Pagination is also available here.<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>id<\/td>\r\n<td>Type: numeric (number)<br \/>Returns only elements with the given ID.<\/td>\r\n<\/tr>\r\n<tr>\r\n<td>search<\/td>\r\n<td>Type: string<br \/>Returns all elements with the given substring.<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n<p>Some examples:<\/p>\r\n<ol>\r\n<li>Getting the city with the ID number: 213:<\/li>\r\n<\/ol>\r\n<p><code>cURL\r\ncURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213' <\/code><button>Copy<\/button> cURL cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213&#8217; Copied to clipboard<\/p>\r\n<ol start=\"2\">\r\n<li>Getting the city with the ID number: 213 with subordinate elements (districts), the number of elements is limited to 100:<\/li>\r\n<\/ol>\r\n<p><code>cURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213&amp;children=true&amp;limit=100' <\/code><button>Copy<\/button> cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213&amp;children=true&amp;limit=100&#8217; Copied to clipboard<\/p>\r\n<ol start=\"3\">\r\n<li>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:<\/li>\r\n<\/ol>\r\n<p><code>cURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213&amp;children=true&amp;limit=100&amp;offset=30' <\/code><button>Copy<\/button> cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213&amp;children=true&amp;limit=100&amp;offset=30&#8217; Copied to clipboard<\/p>\r\n<h4>Search for multiple levels<\/h4>\r\n<p>In order to have search for multiple levels simultaneously, you can use the multi level search endpoint.<\/p>\r\n<p>The address endpoint structure is:<\/p>\r\n<p><code>cURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/search?regions=X&amp;subregions=Y&amp;cities=Z' \r\n--header 'Accept: application\/json' \r\n--header 'Content-Type: application\/json' \r\n--header 'X-API-KEY: ' \r\n--header 'User-Agent: '<\/code><button>Copy<\/button> cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/search?regions=X&amp;subregions=Y&amp;cities=Z&#8217; &#8211;header &#8216;Accept: application\/json&#8217; &#8211;header &#8216;Content-Type: application\/json&#8217; &#8211;header &#8216;X-API-KEY: &#8216; &#8211;header &#8216;User-Agent: &#8216; Copied to clipboard<\/p>\r\n<p>With the following rules:<\/p>\r\n<ul>\r\n<li>the params <strong>regions<\/strong>, <strong>subregions<\/strong>, and <strong>cities<\/strong>\u00a0are required to avoid returning too many results.<\/li>\r\n<li>the param <strong>districts<\/strong> is optional. If omitted, it will display all children districts of the cities that match with the query<\/li>\r\n<li>the query is made with all params considered (AND operations).<\/li>\r\n<\/ul>\r\n<p>Example:<\/p>\r\n<p><code>cURL\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/search?regions=dolno\u015bl\u0105skie&amp;subregions=Wroc\u0142aw&amp;cities=Wroc\u0142aw' <\/code><button>Copy<\/button> cURL curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/search?regions=dolno\u015bl\u0105skie&amp;subregions=Wroc\u0142aw&amp;cities=Wroc\u0142aw&#8217; Copied to clipboard<\/p>\r\n<p>Which will return:<\/p>\r\n<p><code>JSON\r\n{\r\n  \"meta\": {\r\n    \"count_cities\": 1,\r\n    \"count_districts\": 1,\r\n    \"count_regions\": 1,\r\n    \"count_subregions\": 1,\r\n    \"status_code\": 200,\r\n    \"transaction_id\": \"202d252c-fd70-4c37-9908-6382fae42358\"\r\n  },\r\n  \"data\": [\r\n    {\r\n      \"id\": 1,\r\n      \"code\": \"dolnoslaskie\",\r\n      \"name\": \"dolno\u015bl\u0105skie\",\r\n      \"subregions\": [\r\n        {\r\n          \"id\": 381,\r\n          \"region_id\": 0,\r\n          \"code\": \"powiat-wroclaw\",\r\n          \"name\": \"Wroc\u0142aw\",\r\n          \"cities\": [\r\n            {\r\n              \"id\": 39,\r\n              \"subregion_id\": 0,\r\n              \"code\": \"wroclaw\",\r\n              \"name\": \"Wroc\u0142aw\",\r\n              \"districts\": [\r\n                {\r\n                  \"id\": 4,\r\n                  \"city_id\": 0,\r\n                  \"code\": \"psie-pole\",\r\n                  \"name\": \"Psie Pole\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      ]\r\n    }\r\n  ]\r\n}<\/code><button>Copy<\/button> JSON { &#8220;meta&#8221;: { &#8220;count_cities&#8221;: 1, &#8220;count_districts&#8221;: 1, &#8220;count_regions&#8221;: 1, &#8220;count_subregions&#8221;: 1, &#8220;status_code&#8221;: 200, &#8220;transaction_id&#8221;: &#8220;202d252c-fd70-4c37-9908-6382fae42358&#8221; }, &#8220;data&#8221;: [ { &#8220;id&#8221;: 1, &#8220;code&#8221;: &#8220;dolnoslaskie&#8221;, &#8220;name&#8221;: &#8220;dolno\u015bl\u0105skie&#8221;, &#8220;subregions&#8221;: [ { &#8220;id&#8221;: 381, &#8220;region_id&#8221;: 0, &#8220;code&#8221;: &#8220;powiat-wroclaw&#8221;, &#8220;name&#8221;: &#8220;Wroc\u0142aw&#8221;, &#8220;cities&#8221;: [ { &#8220;id&#8221;: 39, &#8220;subregion_id&#8221;: 0, &#8220;code&#8221;: &#8220;wroclaw&#8221;, &#8220;name&#8221;: &#8220;Wroc\u0142aw&#8221;, &#8220;districts&#8221;: [ { &#8220;id&#8221;: 4, &#8220;city_id&#8221;: 0, &#8220;code&#8221;: &#8220;psie-pole&#8221;, &#8220;name&#8221;: &#8220;Psie Pole&#8221; } ] } ] } ] } ] } Copied to clipboard Search for one level<\/p>\r\n<p>To obtain the location id for a certain city or region, you need to execute the following request:<\/p>\r\n<p><code>JSON\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213<\/code><button>Copy<\/button> JSON curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/cities?id=213 Copied to clipboard<\/p>\r\n<p>Change the <strong>path<\/strong> for any of the available ones, also instead of <strong>id<\/strong>, you can use the name of the location level using the parameter <strong>search<\/strong>.<\/p>\r\n<h4>Search Pagination<\/h4>\r\n<p>You only need to set the parameter <strong>limit<\/strong>\u00a0to the exact number you want to use pagination. You can use the pagination limit to avoid returning too many results.<br \/>Example: <code>JSON\r\ncurl --location --request GET 'https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/regions?limit=100<\/code><button>Copy<\/button> JSON curl &#8211;location &#8211;request GET &#8216;https:\/\/api.olxgroup.com\/locations\/v1\/urn:site:otodompl\/regions?limit=100 Copied to clipboard<\/p>\r\n<p>When making this request, you&#8217;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&#8217;ll also find a link to the first page in this object. If there are no results, the links object will be omitted.<\/p>\r\n<h4>Location custom fields<\/h4>\r\n<p>When you send the advert to the RE Partner API, under location object (under data), you can add an extra object called &#8220;custom_fields&#8221;.<br \/>Inside, you can specify the &#8220;city_id&#8221; or the &#8220;district_id&#8221; that you got from the Location search. Also, we will enable the option to send &#8220;street_name&#8221; and &#8220;quarter_name&#8221; as strings.<\/p>\r\n<p>Here&#8217;s the example:<\/p>\r\n<p><code>JSON\r\n{\r\n  \"location\": {\r\n    \"lat\": 101010101, \/\/ mandatory\r\n    \"lon\": 101010101, \/\/ mandatory\r\n    \"exact\": false, \/\/ optional, if set to true we display the street name (if sent)\r\n    \"custom_fields\": { \/\/ optional\r\n      \"city_id\": 12, \/\/ either city_id OR district_id\r\n      \"district_id\": 12, \/\/ either city_id OR district_id\r\n      \"quarter_name\": \"LoremIpsum\", \r\n      \"street_name\": \"LoremIpsum\",\r\n      ...\r\n    }\r\n  }\r\n}<\/code><button>Copy<\/button> JSON { &#8220;location&#8221;: { &#8220;lat&#8221;: 101010101, \/\/ mandatory &#8220;lon&#8221;: 101010101, \/\/ mandatory &#8220;exact&#8221;: false, \/\/ optional, if set to true we display the street name (if sent) &#8220;custom_fields&#8221;: { \/\/ optional &#8220;city_id&#8221;: 12, \/\/ either city_id OR district_id &#8220;district_id&#8221;: 12, \/\/ either city_id OR district_id &#8220;quarter_name&#8221;: &#8220;LoremIpsum&#8221;, &#8220;street_name&#8221;: &#8220;LoremIpsum&#8221;, &#8230; } } } Copied to clipboard<\/p>\r\n<p>As you can see in the example above, the coordinates are still mandatory because we will fall back to coordinates if we don&#8217;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.<\/p>\r\n<p>Location notification<\/p>\r\n<p><strong>Event flow name: \u00a0<\/strong><strong>publish_advert<\/strong><br \/>This flow group events related to\u00a0<strong>advert publish operations<\/strong>. For each operation\/request made, there&#8217;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\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/advert-status-codes\" target=\"_self\" rel=\"noopener\">Advert status codes<\/a>.<\/p>\r\n<p>When something is wrong with your request,\u00a0<strong>related only to the location ids<\/strong>, the advert can be successfully posted, you will get the notification flow from event_type \u00a0<strong>advert_posted_success<\/strong> and a warning message to inform you that the location id does not exist, from event_type <strong>advert_location_error<\/strong>.<\/p>\r\n<p>If the district is wrong, you will receive a notification like the one below, in our callback notification.<\/p>\r\n<p><code>JSON\r\n{\r\n  \"destination\": \"\",\r\n  \"timestamp\": 1646420591327,\r\n  \"event_timestamp\": 1646420591327,\r\n  \"transaction_id\": \"e783c8a2-4adb-476b-88dd-218fbb24d8e5\",\r\n  \"object_id\": \"da9b2722-13e6-4cd9-8112-7106f7e6ddf3\",\r\n  \"flow\": \"publish_advert\",\r\n  \"error_message\": \"Invalid district id: 12\",\r\n  \"data\": {\r\n    \"detail\": \"Invalid district id: 12\",\r\n    \"title\": \"Invalid location.\",\r\n    \"validation\": [\r\n      {\r\n        \"detail\": \"Invalid district id: 12\",\r\n        \"field\": \"district_id\",\r\n        \"title\": \"Invalid location.\"\r\n      }\r\n    ]\r\n  },\r\n  \"event_type\": \"advert_location_error\"\r\n}<\/code><button>Copy<\/button> JSON { &#8220;destination&#8221;: &#8220;&#8221;, &#8220;timestamp&#8221;: 1646420591327, &#8220;event_timestamp&#8221;: 1646420591327, &#8220;transaction_id&#8221;: &#8220;e783c8a2-4adb-476b-88dd-218fbb24d8e5&#8221;, &#8220;object_id&#8221;: &#8220;da9b2722-13e6-4cd9-8112-7106f7e6ddf3&#8221;, &#8220;flow&#8221;: &#8220;publish_advert&#8221;, &#8220;error_message&#8221;: &#8220;Invalid district id: 12&#8221;, &#8220;data&#8221;: { &#8220;detail&#8221;: &#8220;Invalid district id: 12&#8221;, &#8220;title&#8221;: &#8220;Invalid location.&#8221;, &#8220;validation&#8221;: [ { &#8220;detail&#8221;: &#8220;Invalid district id: 12&#8221;, &#8220;field&#8221;: &#8220;district_id&#8221;, &#8220;title&#8221;: &#8220;Invalid location.&#8221; } ] }, &#8220;event_type&#8221;: &#8220;advert_location_error&#8221; } Copied to clipboard<\/p>\r\n","protected":false},"excerpt":{"rendered":"<p>Taxonomy for locations \u2757\ufe0fOnly 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\u00a0solution to mitigate these issues. Coordinates will always&#8230;  <a href=\"https:\/\/doc.olxgroup.com\/api\/?p=758\" title=\"Read Taxonomy for locations\">Read more &raquo;<\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[47],"tags":[],"acf":[],"_links":{"self":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts\/758"}],"collection":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=758"}],"version-history":[{"count":0,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts\/758\/revisions"}],"wp:attachment":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=758"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=758"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=758"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}