Navmii POI Publishing and Search API
- Dmitry Lykov
- Pavel Rakko [SERVERS] (Unlicensed)
Definitions
Publisher – a company posting data to Navmii POI server using publishing API.
Content Type and Encoding
All the data sent within request bodies must be encoded as JSON. The respective content type header should be used, i.e. application/json; charset=UTF-8.
ApiKey
Navmii provides an ApiKey that should be passed in every request as a value of CLIENT_ID request header.
When data becomes available
Published data becomes available within 2 hours. For now, Navmii doesn’t provide services notifying Publishers when published POI data becomes available in Navmii apps.
Categories Method
The method returns the list of categories.
Method | GET |
URL | |
Request | empty |
Sample request: | |
Response | CategoriesResponse object |
Sample response: {"sign":"f8102571-ad9d-4ec8-a4aa-1e6cefa948ec","status":0,"categories":[{"id":1000,"name":"Misc"},{"id":2202,"name":"School"},{"id":10045,"name":"San Francisco Subway"}],"responseTime":0} | |
GetPage Method
The method returns the view with POI’s details.
Method | GET |
URL | http://livepoi.navmii.com/p/view/<POI’s ID> |
Request | empty |
Sample request: http://livepoi.navmii.com/p/view/9FC4A443-D4F7-4708-9013-0004052EC7A5 | |
Response | View with POI data |
Search Method
The method allows to search for existing listings.
Method | GET |
URL | |
Request | empty |
Sample request: http://livepoi.navmii.com/v2/s?q=pizza&top=100&lat=59.933347&lon=30.329675&r=2000 | |
Response | PoiSearchResponse object |
Sample response: {"sign":"0c94442b-0406-4853-8ce4-32dd0e8d52dd","status":0,"categories":[{"id":7315,"name":"Restaurant"},{"id":9376,"name":"Café\/Pub"}],"responseTime":"1201.0768","count":2,"poiList":[{"autoId":22993798,"categories":[{"id":9376}],"categoryIds":[9376],"categoryName":"","country":"RU","created":1428952153010,"defaultImageUrl":"","extID":"1289216453","fullInfo":{"FormatType":0,"URI":"http:\/\/livepoi.navmii.com\/V2\/v\/c197120a-1c2d-4a16-b89f-f733a4423f3d"},"id":"c197120a-1c2d-4a16-b89f-f733a4423f3d","location":{"lat":59.93316,"lon":30.36034},"name":"Koti pizza","provider":"OSM","shortInfo":"","specialOffer":{"message":"","title":""},"stats":{"Likes":0,"ReviewsCount":0,"UserRating":0},"status":2,"updated":1433669871617},{"autoId":23042523,"categories":[{"id":7315}],"categoryIds":[7315],"categoryName":"","country":"RU","created":1428952604733,"defaultImageUrl":"","extID":"1683446407","fullInfo":{"FormatType":0,"URI":"http:\/\/livepoi.navmii.com\/V2\/v\/e2df149f-7840-46e7-99e7-869246b6b216"},"id":"e2df149f-7840-46e7-99e7-869246b6b216","location":{"lat":59.94408,"lon":30.35842},"name":"Pizza Hut","provider":"OSM","shortInfo":"","specialOffer":{"message":"","title":""},"stats":{"Likes":0,"ReviewsCount":0,"UserRating":0},"status":2,"updated":1433671681750}]} | |
Query string parameters | |||
Name | Mandatory | Description | Example |
q | Yes | Name, the first symbols of name, part of address, phone (see phone specification). Minimum 2 characters. | Pizza |
top | No | Maximum number of items to be returned | 100 |
lat | Yes | Latitude of the center of the search area, degrees. | 51.510132 |
lon | Yes | Longitude of the center of the search area, degrees. | 0.134469 |
r | No | Search radius (in meters). Default value is 30’000. | 1600 |
phone | No | Location's phone number. Part of phone number. Minimum 4 characters. | 2126518966 |
Details Method
The method allows to retrieve listing details using the specified listing ID.
Method | GET |
URL | http://livepoi.navmii.com/V2/v/<listing ID> |
Request | empty |
Sample request: http://livepoi.navmii.com/v2/v/c197120a-1c2d-4a16-b89f-f733a4423f3d | |
Response | PoiDetailsResponse object |
Sample response: {"sign":"35067c76-517f-49f4-880d-c87fa7641f6c","status":0,"poiInfo":{"autoId":0,"categories":[{"id":9376}],"categoryIds":[9376],"categoryName":"Café\/Pub","id":"c197120a-1c2d-4a16-b89f-f733a4423f3d","location":{"lat":59.93316,"lon":30.36034},"name":"Koti pizza","specialOffer":{"message":"","title":""},"dataLists":[],"description":"","phones":[null]}} | |
Order Method
The method allows to add a new listing to Navmii POI server.
Method | POST |
URL | |
Request | PoiItem object |
HTTP headers | ALLOWED_DUPLICATE=1. If this option is selected, the POI creation does not check for similar POIs from other providers near these coordinates. This parameter is valid for the Yext and Uberall providers. |
Sample request: {"publisherId": "9DEA59CA-49AC-44D8-A5EF-D521AF369423","name":"Zoologischer Garten Berlin","address":{"visible": false, "address":"Hardenbergplatz 8","address2":"","city":"Berlin","postalCode":"10787"},"phones":[{"number":{"number":"+49 30 254010"}}],"categories":[{"id":7311,"name":"Petrol Station"},{"id":2304,"name":"Car Wash"}],"description":"Entdecken Sie im Zoo Berlin, dem ersten Tiergarten Deutschlands, die artenreiche Tierwelt. Hier leben nicht nur exotische Zootiere wie Eisbären, Elefanten, Robben, Löwen oder Giraffen. Auch viele vom Aussterben bedrohte Haustierrassen können Sie bei uns besuchen.","images":[{"url":"https://uberall.com/uploads/userpics/250173/rouGELwZI5.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/Kmi0W6LnF4.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/T9nXMYmycV.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/VHqaBCt0Ac.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/CilgQsHmxd.png"},{"url":"https://uberall.com/uploads/userpics/250173/qCbSgV8mFU.png"},{"url":"https://uberall.com/uploads/userpics/250173/xZTSZJ3S6h.jpg"}],"geoData":{"displayLatitude":52.5069278,"displayLongitude":13.3342062},"videos":[{"url":"https://www.youtube.com/watch?v=VWkb3gAwHsI"}],"paymentOptions":["Mastercard","VISA","EC","Cash"]} | |
Response | ApiResponse object |
Sample response: {"sign":"2628d5fb-ac90-48fb-bdb1-5f31829765c0","status":0,"partnerId":"326bb88d-0123-4caa-b3f2-672a1e4e11f1","poiStatus":"LIVE","publisherId":"9DEA59CA-49AC-44D8-A5EF-D521AF369423"} | |
Update Method
The method allows to replace the existing listing with the new one.
Method | PUT |
URL | http://livepoi.navmii.com/navmiiapilistings/<listing ID> |
Request | PoiItem object |
Sample request: {"publisherId": "9DEA59CA-49AC-44D8-A5EF-D521AF369423", "name":"Zoologischer Garten Berlin","address":{"visible": false, "address":"Hardenbergplatz 8","address2":"","city":"Berlin","postalCode":"10787"},"phones":[{"number":{"number":"+49 30 254010"}}],"categories":[{"id":7311,"name":"Petrol Station"},{"id":2304,"name":"Car Wash"}],"description":"Entdecken Sie im Zoo Berlin, dem ersten Tiergarten Deutschlands, die artenreiche Tierwelt. Hier leben nicht nur exotische Zootiere wie Eisbären, Elefanten, Robben, Löwen oder Giraffen. Auch viele vom Aussterben bedrohte Haustierrassen können Sie bei uns besuchen.","images":[{"url":"https://uberall.com/uploads/userpics/250173/rouGELwZI5.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/Kmi0W6LnF4.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/T9nXMYmycV.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/VHqaBCt0Ac.jpg"},{"url":"https://uberall.com/uploads/userpics/250173/CilgQsHmxd.png"},{"url":"https://uberall.com/uploads/userpics/250173/qCbSgV8mFU.png"},{"url":"https://uberall.com/uploads/userpics/250173/xZTSZJ3S6h.jpg"}],"geoData":{"displayLatitude":52.5069278,"displayLongitude":13.3342062},"videos":[{"url":"https://www.youtube.com/watch?v=VWkb3gAwHsI"}],"paymentOptions":["Mastercard","VISA","EC","Cash"]} | |
Response | ApiResponse object |
Sample response: {"sign":"c59fa3bb-b3cb-45b2-b990-91884972fe41","status":0,"partnerId":"326bb88d-0123-4caa-b3f2-672a1e4e11f1","poiStatus":"LIVE","publisherId":"9DEA59CA-49AC-44D8-A5EF-D521AF369423"} | |
Cancel Method
The method is used to delete an existing listing from Navmii POI server. This method effectively undoes an ORDER request. When a listing is CANCELed, Navmii removes all its content provided by Publisher, but keeps the name, address, phone number, and categories, or reverts the listing to the state it was in before it was published.
Method | DELETE |
URL | http://livepoi.navmii.com/navmiiapilistings/<listing ID> |
Request | empty |
Sample request: http://livepoi.navmii.com/navmiiapilistings/326bb88d-0123-4caa-b3f2-672a1e4e11f1 | |
Response | GeneralResponse object |
Sample response: {"sign":"3fbb037b-d060-4ede-a1f4-51f9be608428","status":0} | |
Stats Method
The method is used to track POI stats. The method’s parameters:
“apikey” – the client’s API key. Mandatory.
“from” – the first date of the report. Mandatory.
“to” – the last date of the report. Mandatory.
“days” – if 1, then the report is ordered by days. Optional.
“venues” – if 1, then the report is ordered by venues. Optional.
“id” – the report is generated for the spesified POI. Optional.
Method | GET |
URL | |
Request | empty |
Sample request: http://livepoi.navmii.com/navmiiapilistings/stats?apikey=value&from=2016-03-01&to=2016-03-07 | |
Response | |
Sample response: {"sign":"1472551003","status":0,"t":0,"items":[{"action":"","count":27,"date":null,"id":null,"os":"","source":"","target":""},{"action":"click","count":483,"date":null,"id":null,"os":"iPhone","source":"detailspage","target":"directions"},{"action":"click","count":249,"date":null,"id":null,"os":"Android","source":"detailspage","target":"directions"},{"action":"click","count":32,"date":null,"id":null,"os":"iPad","source":"detailspage","target":"directions"},{"action":"click","count":62,"date":null,"id":null,"os":"","source":"detailspage","target":"directions"},{"action":"click","count":1205,"date":null,"id":null,"os":"iPhone","source":"detailspage","target":"map"},{"action":"click","count":650,"date":null,"id":null,"os":"Android","source":"detailspage","target":"map"},{"action":"click","count":132,"date":null,"id":null,"os":"iPad","source":"detailspage","target":"map"},{"action":"click","count":2,"date":null,"id":null,"os":"","source":"detailspage","target":"map"},{"action":"impression","count":971,"date":null,"id":null,"os":"iPhone","source":"detailspage","target":""},{"action":"impression","count":467,"date":null,"id":null,"os":"Android","source":"detailspage","target":""},{"action":"impression","count":85,"date":null,"id":null,"os":"iPad","source":"detailspage","target":""},{"action":"impression","count":377518,"date":null,"id":null,"os":"iPhone","source":"serp","target":""},{"action":"impression","count":118818,"date":null,"id":null,"os":"Android","source":"serp","target":""},{"action":"impression","count":16435,"date":null,"id":null,"os":"iPad","source":"serp","target":""}]} | |
Request Objects
PoiItem object | |||
Field | Type | Mandatory | Comment |
publisherId | string | Yes | Unique listing ID provided by the Publisher |
status | string | No | |
geoData | GeoData object | No | |
paymentOptions | list of strings | No | |
address | Address object | No | |
description | string | No | |
name | string | No | |
serviceArea | ServiceArea object | No | |
categories | list of PoiCategory objects | No | |
bios | list of Bio objects | No | |
specialOffer | SpecialOffer object | No | |
images | list of Image objects | No | |
promotions | list of Promotion objects | No | |
videos | list of Video objects | No | |
matchPhones | list of PhoneNumber objects | No | |
hours | list of Hour objects | No | |
urls | list of Url objects | No | |
phones | list of Phone objects | No | |
GeoData object | |||
Field | Type | Mandatory | Comment |
displayLatitude | double | No | Latitude of the POI |
displayLongitude | double | No | Longitude of the POI |
routableLatitude | double | No | |
routableLongitude | double | No | |
Address object | |||
Field | Type | Mandatory | Comment |
address | string | No | |
address2 | string | No | |
city | string | No | |
county | string | No | |
state | string | No | |
postalCode | string | No | |
visible | bool | Yes | |
countryCode | string | No | |
ServiceArea object | |||
Field | Type | Mandatory | Comment |
radius | double | No | |
postalCodes | list of PostalCode objects | No | |
PostalCode object | |||
Field | Type | Mandatory | Comment |
Code | string | No | |
PoiCategory object | |||
Field | Type | Mandatory | Comment |
id | int | No | |
name | string | Yes | |
Bio object | |||
Field | Type | Mandatory | Comment |
name | string | No | |
description | string | No | |
image | Image object | No | |
Image object | |||
Field | Type | Mandatory | Comment |
url | string | Yes | |
width | int | No | |
height | int | No | |
description | string | No | |
SpecialOffer object | |||
Field | Type | Mandatory | Comment |
message | string | No | |
url | string | No | |
start | string | No | |
end | string | No | |
Promotion object | |||
Field | Type | Mandatory | Comment |
text | string | Yes | |
Video object | |||
Field | Type | Mandatory | Comment |
url | string | No | |
description | string | No | |
type | string | No | |
PhoneNumber object | |||
Field | Type | Mandatory | Comment |
countryCode | int | No | |
number | string | Yes | |
formatted | string | No | |
Hour object | |||
Field | Type | Mandatory | Comment |
day | string | Yes | |
intervals | list of Interval objects | No | |
Interval object | |||
Field | Type | Mandatory | Comment |
start | string | No | |
end | string | No | |
Url object | |||
Field | Type | Mandatory | Comment |
url | string | No | |
displayUrl | string | No | |
description | string | No | |
Phone object | |||
Field | Type | Mandatory | Comment |
type | string | No | |
number | PhoneNumber object | Yes | |
Response Objects
PoiSearchResponse object | |||
Field | Type | Mandatory | Comment |
sign | string | No | |
status | int | Yes | |
poiList | list of POI objects | No | |
count | int | No | |
categories | list of PoiCategory objects | No | |
responseTime | string | No | |
POI object | |||
Field | Type | Mandatory | Comment |
id | GUID | Yes | Unique identifier of the listing |
autoId | int | Yes | For system use |
extID | string | No | Unique listing ID provided by the Publisher (If nothing was provided by the Publisher the system generated a new GUID and saved it to this field) |
country | string | No | ISO2 country code |
iso3Code | string | No | ISO3 country code |
provider | string | No | |
rank | int | No | |
name | string | Yes | Name of the listing |
officialLocalName | string | No | |
subtype | string | No | |
shortInfo | string | No | |
categoryName | string | No | |
defaultImageUrl | string | No | |
address | Address object | No | |
location | Point object | No | |
tags | string | No | |
status | int | No | |
cult | string | No | Culture |
stats | Statistics object | No | |
phone | PhoneNumber object | No | |
string | No | ||
categoryIds | list of int | No | |
categories | list of Category objects | No | |
specialOffer | SpecialOffer object | No | |
fullInfo | FullInfo object | No | |
trackingUrls | list of Url objects | No | |
like | int | No | |
dislike | bool | No | |
isOpenedNow | bool | No | |
hotelRank | int | No | |
spaces | int | No | |
description | string | No | |
OpeningHoursSummary | DataList object | No | |
OpeningHoursToday | string | No | |
dataLists | list of DataList objects | No | |
images | list of Image objects | No | |
videos | list of Video objects | No | |
hours | list of Hours objects | No | |
urls | list of Url objects | No | |
phones | list of PhoneNumber objects | No | |
icon | string | No | |
addressReverse | Address object | No | Address that Navmii found out using OSM maps |
Address object | |||
Field | Type | Mandatory | Comment |
address | string | No | |
address2 | string | No | |
crossing | string | No | |
city | string | No | |
county | string | No | |
country | string | No | |
state | string | No | |
postalCode | string | No | |
countryCode | string | No | |
Point object | |||
Field | Type | Mandatory | Comment |
lat | double | Yes | Latitude |
lon | double | Yes | Longitude |
PhoneNumber object | |||
Field | Type | Mandatory | Comment |
type | int | No | |
cc | int | No | Country code |
number | string | Yes | |
description | string | No | |
formatted | string | No | |
Statistics object | |||
Field | Type | Mandatory | Comment |
likes | int | No | |
rating | double | No | |
reviews | int | No | |
Category object | |||
Field | Type | Mandatory | Comment |
id | int | Yes | |
SpecialOffer object | |||
Field | Type | Mandatory | Comment |
message | string | No | |
title | string | No | |
url | string | No | |
period | TimePeriod object | No | |
start | datetime | No | |
end | datetime | No | |
TimePeriod object | |||
Field | Type | Mandatory | Comment |
start | datetime | No | |
end | datetime | No | |
FullInfo object | |||
Field | Type | Mandatory | Comment |
url | string | Yes | |
format | int | Yes | |
Url object | |||
Field | Type | Mandatory | Comment |
url | string | No | |
displayText | string | No | |
description | string | No | |
type | string | No | |
PoiCategory object | |||
Field | Type | Mandatory | Comment |
id | int | No | |
name | string | Yes | |
PoiDetailsResponse object | |||
Field | Type | Mandatory | Comment |
sign | string | No | |
status | int | Yes | |
poiInfo | POI object | No | |
DataList object | |||
Field | Type | Mandatory | Comment |
title | string | No | |
type | string | Yes | |
order | int | No | |
currency | string | No | |
displayAs | int | No | |
listDelimiter | string | No | |
items | list of DataListItem objects | Yes | |
isLocalized | bool | Yes | |
DataListItem object | |||
Field | Type | Mandatory | Comment |
key | string | No | |
numValue | double | No | |
strValue | string | No | |
highlighted | bool | No | |
Image object | |||
Field | Type | Mandatory | Comment |
url | string | Yes | |
width | int | No | |
height | int | No | |
description | string | No | |
type | int | No | |
group | string | No | |
Video object | |||
Field | Type | Mandatory | Comment |
url | string | No | |
description | string | No | |
type | string | No | |
Hours object | |||
Field | Type | Mandatory | Comment |
day | string | Yes | |
ApiResponse object | |||
Field | Type | Mandatory | Comment |
sign | string | No | |
status | int | Yes | |
poiStatus | string | Yes | |
partnerId | GUID | No | Unique identifier of the listing provided by Navmii |
publisherId | string | No | |
url | string | No | |
conflict | string | No | |
error | string | No | |
GeneralResponse object | |||
Field | Type | Mandatory | Comment |
sign | string | No | |
status | int | Yes | |
CategoriesResponse object | |||
Field | Type | Mandatory | Comment |
sign | string | No | |
status | int | Yes | |
categories | list of PoiCategory objects | No | |
responseTime | double | No | Response time (sec) |