Network Lookup
Interface Description
HTTP GET v1.01

Document name:HTTP GET v1.01
Document number:EMK16001SSL
Revision:1.0
Author:Martin Kristell
Date:2016-08-15
Information class:Open Information
Reviewer:Jonas Rexeke
Review date:2016-08-15
Company:SPIRIUS AB
VAT/REG number:556788-4183
Postal address:Box 67
371 21 KARLSKRONA
Telephone number:+46 (455) 65 55 00
Fax number:+46 (455) 65 55 19
Home page:www.spirius.com

© Copyright SPIRIUS AB 2018

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. SPIRIUS AB shall have no liability for any error or damages of any kind resulting from use of this document.

1. INTRODUCTION

1.1 Scope

This document describes the SPIRIlookup HTTP GET Interface. It gives the basics of how to use the API and provides a list of available parameters. The document is intended for application developers and/or integrators. Basic knowledge of the HTTP protocol is assumed.

2. HTTP GET INTERFACE

2.1 Service Levels

Three different service levels are available.

  • Sweden – Lookup the current mobile phone operator for a Swedish mobile phone number. Lookup is performed in a local database that contains number portability information provided by Swedish Number Portability Administrative Center. The returned information is never older than 48 hours.
  • Basic – Lookup subscriber status and IMSI from the Home Location Register (HLR) with a live SRI for SM request sent over the SS7 network to the HLR handling the subscriber for the provided MSISDN. A SRI for SM request typically need between 0.3 and 0.8 seconds to execute.
  • Advanced – Combines the information from both Sweden and Basic in a single request. Access to database lookup and HLR lookup is granted separately.

2.1.1 Access points

Two different accesspoints are available. One in Stockholm and another in Karlskrona. Regardless of which accesspoint that is being used each new connection is loadbalanced over the same set of available backend servers. The reason for providing two different accesspoints is to provide an alternative if one of the sites will experience a power failure or suffer from DDOS attack. The two accesspoints are:

https://get1.spirilookup.spirius.com:54011

https://get2.spirilookup.spirius.com:54011

You can also omit the number and send requests to get.spirilookup.spirius.com, but note that this DNS entry is identical to get1.spirilookup.spirius.com and does not provide any failover functionality.

2.1.2 Request syntax

The requests are secured by HTTPS and authenticated using Basic Authentication as defined in RFC 2617 (Credentials are encoded in the Authorization request-header field). To send a request you send a REST-style URI containing the API version, service and MSISDN. https://get1.spirilookup.spirius.com:54011/v1/lookup/sweden/46712345678 If you enter a request from a web-browser you will be promted for credentials by a popup dialog.

2.1.3 Response syntax

The reponse will be json-encoded and contain different fields depending on which service that is requested. Sample response from an advanced lookup request (i.e. containg all fields) for number +46712345678:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Type: text/plain;charset=utf-8
{
"CC": "", 
"Country": "", 
"HLR": "HLR_LOCAL_CANCEL", 
"IMSI": "", 
"MCC": "", 
"MNC": "", 
"Operator": "", 
"R": 200, 
"SPID": ""
}

Should there be anything wrong with the request, it will be rejected with an HTTP error indicating the nature of the problem, please see section of Response codes below.

2.1.4 HTTP Error Codes

CodeResponseDescription
200OKRequest was received and processed.
401UnauthorizedWrong user or password, or user lack access rights for SPIRIlookup. It could also be that the account is inactive in case the contract has been terminated.
403ForbiddenUser lack access right to requested service
400Bad RequestInvalid MSISDN.
503Service UnavailableThe server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

2.1.5 Response Codes for Sweden service

Response CodeDescription
0The request was successful. For a mobile network operator, MNC and Operator name are given in the response. For a MVNO the first part of IMSI is present in the response instead of MNC (as MVNO don’t have MNC).
11Mandatory parameter MSISDN is not a valid Swedish phone number
16Given MSISDN is not a mobile phone number, it could be a geographical (land line) number.

2.1.6 Response Codes for Basic and Advanced services

For Advanced service, an error from the SRI for SM request take precedence over an error from the Sweden service.

Response CodesHLRDescription
0OKThe request was successful. First part of IMSI is present in the response.
100SYSTEM_FAILUREThe HLR responded to the SRI for SM request with an error indicating that a system failure occurred in the HLR while processing the request.
101DATA_MISSINGThe HLR responded to the SRI for SM request with an error indicating the data was missing.
103FACILITY_NOT_SUPPORTEDThe HLR responded to the SRI for SM request with an error indicating that short message facility is not supported.
104UNKNOWN_SUBSCRIBERThe HLR responded to the SRI for SM request with an error indicating there is no subscriber for the given MSISDN.
105TELE_SERVICE_NOT_PROVISIONEDThe HLR responded with an error indicating that SMS teleservice is not provisioned for the subscriber.
106CALL_BARREDThe HLR responded to the SRI for SM request with an error indicating the SMS service is barred for the subscriber.
107ABSENT_SUBSCRIBER_SMThe HLR responded to the SRI for SM request with an error indicating the subscriber is not connected to the network.
200HLR_ABORTThe HLR (or some other entity in the network) aborted the SRI for SM request.
200HLR_LOCAL_CANCELNo response for the SRI for SM request was received.
299TIMEOUTNo response for the SRI for SM request was received.
999HLR_REJECTThe HLR rejected the SRI for SM request.

5. APPENDIX

5. 1 Document History

RevisionDateSignatureComments
1.02016-05-27MKFirst revision 1.0
1.012016-08-15MKUpdated examples in section 4.1 and 4.2

5.2 Terminology

Abbreviation
Explanation
HLRHome Location Register
HTTPHypertext Transfer Protocol
IMSIInternational Mobile Subscriber Identity
MSISDNMobile Subscriber Integrated Services Digital Network Number
SRI for SMSend Routing Info For Short Message
SS7Signalling System Number 7
SNPACSwedish Number Portability Administrative Center
RFCRequest for Comments, a publication from the Internet Engineering Task Force
MCCMobile Country Code
MNCMobile Network Code
MVNOMobile Virtual Network Operator (do not have their own radio access network)