The JSON approach is mainly intended for intranet integration, while the xml version is for machine to machine integration.

Transcription

1 1881 Partner Search API The Partner Search API is a RESTFull service that utilizes the HTTP/GET verb. Parameters are passed in the querystring of the HTTP request. The service can produce both xml and JSON formatted data. The JSON approach is mainly intended for intranet integration, while the xml version is for machine to machine integration. Search: Parameter name Mandatory Description username Yes The user name assigned to the customer by password Yes The password assigned to the customer by msisdn Yes The a-number of the end-user performing the search. query No The search query. Should be url encoded. format No Set to json for JSON formatted data. Remove this parameter or set to xml for XML formatted data. level No Defines the amount of data to return. level=0;minimum amount of data level=1;includes address information level=2;additional company/person information (lower performance) catalogueids No Catalogueid=0; public person listings Catalogueid=1; public company listings Catalogueid=5; internal catalogue If this is empty, all available catalogues is included the list of id s is separated by. pagesize No Number of hits to return. Maximum value allowed is 300. page No The page to return in the result set. If empty the first page will be shown. geocodes No Geo code pairs separated with. Pair is presented in the following way: Latitude:Longitude Lat/long is encoded like : : Invalid formatted geocodes will be ignored. xmlns No Namespace is by default included in xml format. To exclude set xmlns=0. Extended parameters for advanced search: firstname No FirstName. Should be url encoded. lastname No LastName/CompanyName. Should be url encoded. phone No Phone, mobile, fax. Should be url encoded. street No Street. Should be url encoded. postalcode No PostalCode. Should be url encoded. postalarea No PostalArea. Should be url encoded. region No Region: Østlandet,Vestlandet,Nord-Norge,Midt-Norge,

2 Sørlandet. Should be url encoded. municipality No Municipality. Should be url encoded. /search?username=<username>&msisdn=<msisdn>&password=<password>&query=<query>&le vel=0&format=json Example advanced search: /search?username=<username>&msisdn=<msisdn>&password=<password>&firstname=<firstna me>&lastname=<lastname>&postalcode=<postalcode>&level=0&format=json Details: If you want to receive a specific resultitem and get more details you can use this one: Parameter name Mandatory Description username Yes The user name assigned to the customer by password Yes The password assigned to the customer by msisdn Yes The a-number of the end-user performing the search. itemid Yes The result itemid. From resultlist: Results.ResultItem. ItemId format No Set to json for JSON formatted data. Remove this parameter or set to xml for XML formatted data. xmlns No Namespace is by default included in xml format. To exclude set xmlns=0. /search/details?username=<username>&msisdn=<msisdn>&password=<password>&itemid=<it emid>&format=json GetCatalogues: If you want to receive the catalogues connected to the user you can use this one: Parameter name Mandatory Description username Yes The user name assigned to the customer by password Yes The password assigned to the customer by msisdn Yes The a-number of the end-user performing the search. format No Set to json for JSON formatted data. Remove this parameter or set to xml for XML formatted data. xmlns No Namespace is by default included in xml format. To exclude set xmlns=0. /search/getcatalogues?username=<username>&msisdn=<msisdn>&password=<password>&for mat=json

3 Search result Field name Description StatusMessage Contains an error message if the search fails, otherwise empty TotalNumberOfResults The number of hits Results The actual hits

4 .net proxy 1881 has developed a proxy for the service with strong typed message classes. The latest proxy can be downloaded from const string ApiUrl = " //GetResult - list var qlist = new SearchQuery Msisdn = "########", Password = "******", UserName = "########", QueryLevel = QueryLevels.Medium, Query = "opplysningen", PageSize = "5", Page = "1", IncludedCatalogues = new List<string>() "0","1" ; using (var target = new SearchProxy()) var result = target.getresult(new Uri(ApiUrl), qlist); //TODO: do something with the result //GetResult - listitem var qlistitem = new SearchQuery Msisdn = "########", Password = "******", UserName = "########", ItemId = " S1" ; using (var target = new SearchProxy()) var result = target.getresult(new Uri(ApiUrl), qlistitem); //TODO: do something with the result //GetCatalogues var qcatalogues = new SearchCataloguesRequest Msisdn = "########", Password = "******", UserName = "########" ; using (var target = new SearchProxy()) var result = target.getsearchcatalogues(new Uri(ApiUrl), qcatalogues); JQuery sample: <script type="text/javascript" language="javascript"> var username = "########"; var msisdn = "########"; var password = "*****"; $(document).ready(function () //need to user charset=iso in order to get Norwegian characters correct to the search service. $("#QueryBox").autocomplete(

5 source: function (request, response) $.ajax( contenttype: "application/x-www-form-urlencoded;charset=iso ", url: GetSearchUrl(), type: "GET", datatype: "json", success: function (data) response($.map(data.results, function (item) return label: GetName(item) + "(" + GetPhone(item) + ")", value: GetName(item), code: GetPhone(item) ; )), error: function (data) $("#Phone")[0].innerText = "an error occurred while reading search service"; ), select: function (data) $("#Code").value = data.item; $("#Phone").val(data.item);, minlength: 1 ) ); function GetName(item) if (item.companyname!= null) return item.companyname; return item.firstname + " " + item.lastname; function GetSearchUrl() var data = "/search?username=" + username + "&msisdn=" + msisdn + "&password=" + password + "&query=" + $.URLEncode($("#QueryBox").val()) + "&level=0&format=json"; $("#SearchUrl")[0].innerText = data; return data; function GetPhone(item) if (item.contactpoints == null) return ""; for (var i = 0; i < item.contactpoints.length; i++) if (item.contactpoints[i].contactpointtype == 2) return item.contactpoints[i].address; return ""; $("#QueryBox").bind("autocompleteselect", function (event, ui) $("#Code").val(ui.item.label); $("#Phone")[0].innerText = ui.item.code; ); $.extend( URLEncode: function (c) var o = ''; var x = 0; c = c.tostring(); var r = /(^[a-za-z0-9_.]*)/; while (x < c.length) var m = r.exec(c.substr(x)); if (m!= null && m.length > 1 && m[1]!= '') o += m[1]; x += m[1].length; else if (c[x] == ' ') o += '+'; else var d = c.charcodeat(x); var h = d.tostring(16); o += '%' + (h.length < 2? '0' : '') + h.touppercase(); x++;

6 return o;, URLDecode: function (s) var o = s; var binval, t; var r = /(%[^%]2)/; while ((m = r.exec(o))!= null && m.length > 1 && m[1]!= '') b = parseint(m[1].substr(1), 16); t = String.fromCharCode(b); o = o.replace(m[1], t); return o; ); </script> Example result set: <?xml version="1.0"?> <SearchResponse xmlns:xsd=" xmlns:xsi=" xmlns=" <Results> <ResultItem> <Addresses /> <BirthDate xsi:nil="true" /> <Collection>B2B</Collection> <ContactPoints> <Address> </Address> <ContactPointType>Landline</ContactPointType> <Address>[email protected]</Address> <ContactPointType> </ContactPointType> <Address> </Address> <ContactPointType>Mobile</ContactPointType> <Address> <ContactPointType>HomePage</ContactPointType> </ContactPoints> <FirstName>Jonas</FirstName> <Gender>Unknown</Gender> <ItemId>b2b </ItemId> <LastName>Syrstad</LastName> <ResultType>Person</ResultType> </ResultItem> </Results> <TotalNumberOfResults>1</TotalNumberOfResults> </SearchResponse> ResultItem enum fields Field name Addresses.Address_Search.AddressType ContactPoints.ContactPoint_Search. ContactPointType Values Visiting, Postal, Billing HomePage,

7 ContactPoints.ContactPoint_Search.IsMain , Mobile, Landline, Fax True, False Collection Contacts, B2B Contacts: collection from 1881.no - Person /1881.no - Company B2B: collection from catalogues defined in B2B (employee/internal catalogues) ResultType Person, Company