Listings API

Table of Contents

1 Easy Connect AS directory information API

The directory information API is Easy Connects search interface for integration in websites or applications. It searches in our complete directory of private persons and businesses in Norway. It is a multi-purpose API suited to many different use cases: directory information website, form auto-fill for e-commerce, CRM software and more.

Our own directory service at http://1890.no/ is 100% backed by our APIs.

The API is a HTTP REST API where queries are GET queries and responses are JSON documents.

For access contact us at post@easyconnect.no or call 53 20 53 00.

1.1 Authentication

Access to the service is controlled with HTTP Basic Authentication1 and optionally limited by IP address.

In this document the following URL scheme is used: https://accountname:key@api.easyconnect.no/. The links use a demo user with the username "demo" and the API key "3505cee9f9d34b4baf59bf60dbb0f9d5". Note that this account is only to be used for demonstration purposes and has strict usage limits. To make these requests with a user agent that does not support username/password in URL set the following Authorization header:

Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

1.1.1 Account name and API key

In the notation used in RFC 7617 the account name is used as user-id and the API key as password.

Example request: https://account:key@api.easyconnect.no/

1.1.2 Password-less

Optionally the account can be configured without an API key but with access limited by IP address/subnet (IPv4 and/or IPv6).

Example request: https://account@api.easyconnect.no/

1.2 Response codes

The API responds with the following HTTP response codes:

200
OK. The request was successful.
400
Bad Request. Invalid request parameters or headers.
401
The request did not contain an Authorization header.
403
Access denied. Either the account name or key is invalid or the IP address does not have access.
404
Not Found. Requested endpoint does not exist or (for some endpoints) the requested entity does not exist.
429
Too Many Requests. Either the account has exceeded contractually defined usage limits or the API service is overloaded.
500 - 599
Internal error.

1.3 Instances

There are two public instances of the API: api.easyconnect.no and beta.api.easyconnect.no. All endpoints under these are identical, the main difference is SLA. Unless explicitly directed to by Easy Connect AS customers should use api.easyconnect.no.

Select customers with special customization, capacity or SLA requirements can get dedicated instances.

1.4 Stability

All endpoints, parameters and response structures documented in this document are considered stable. Customers will be notified about breaking changes well in advance.

Some endpoints may return more fields than what is documented. Undocumented fields may be changed or removed at any time. New fields can also be added.

2 Listings API

2.1 API endpoints

2.1.1 /listings

Full text search in directory listings. We have developed a set of techniques for full text search well suited for directory service data and typical user queries.

Parameter Data type Required Description
fulltext string true Search string. Name, phone number, address, …
page_size integer [0-1000] false (default: 20) Maximum number of results per request.
page integer false The pagination index.
zip string false Filter results by postal code.
city string false Filter results by postal city.
municipality_code string false Filter results by municipality code (kommunenr.).
county_code string false Filter results by county code (fylkesr.).
houseno integer false Filter results by house number.
letter string false Filter results by house letter (bokstav i husnr.).
sector string false Filter results by sector (business or consumer).

Returns a Listing search results response structure.

Example: /listings?fulltext=Easy%20Connect%20AS%2C%20Bergen2

GET /listings?fulltext=Easy%20Connect%20AS%2C%20Bergen HTTP/1.1
Host: api.easyconnect.no
Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result_size": 1,
  "page_size": 20,
  "next_page": "/listings?fulltext=Easy+Connect+AS%2C+Bergen&page=1",
  "listings": [
    {
      "sector": "business",
      "link": "Easy-Connect-AS",
      "displayname": "Easy Connect AS",
      "telenumbers": [
        {
          "usage_type": "normal",
          "terminal_type": "phone",
          "number": "53205300"
        }
      ],
      "street": "Midtunhaugen",
      "houseno": 10,
      "zip": "5224",
      "city": "Nesttun",
      "municipality": "Bergen",
      "county": "Hordaland",
      "street_id": "120133828",
      "municipality_code": "1201",
      "county_code": "12",
      "geoquality": "A",
      "displayaddress": "Midtunhaugen 10, 5224 Nesttun",
      "lat": 60.3189882162208,
      "lon": 5.36295661961305,
      "email": "post@easyconnect.no",
      "nace_1": "63.120",
      "nacetitle_1": "Drift av web-portaler",
      "orgno": "981176553",
      "website": "http://www.easyconnect.no/",
      "more": {
        "listings_on_address": "/listings/address?houseno=10&letter=&street_id=120133828",
      }
    }
  ],
  "more": {
    "search_suggestions": "/listings/search_suggestions?fulltext=Easy+Connect+AS%2C+Bergen"
  }
}

2.1.2 /listings/phone

Lookup of a listing by phone number. The phone number can be specified as just a local Norwegian number (``53205300'', ``53 20 53 00'') or with an international prefix (``4753205300'', ``+4753205300'', ``004753205300'').

Returns a Listing search results response structure.

Example: /listings/phone?number=532053003

GET /listings/phone?number=53205300 HTTP/1.1
Host: api.easyconnect.no
Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "next_page": "/listings/phone?number=53205300&page=1",
  "page_size": 20,
  "result_size": 1,
  "listings": [
    {
      "sector": "business",
      "link": "Easy-Connect-AS",
      "displayname": "Easy Connect AS",
      "telenumbers": [
        {
          "usage_type": "normal",
          "terminal_type": "phone",
          "number": "53205300"
        }
      ],
      "street": "Midtunhaugen",
      "houseno": 10,
      "zip": "5224",
      "city": "Nesttun",
      "municipality": "Bergen",
      "county": "Hordaland",
      "street_id": "120133828",
      "municipality_code": "1201",
      "county_code": "12",
      "geoquality": "A",
      "displayaddress": "Midtunhaugen 10, 5224 Nesttun",
      "lat": 60.3189882162208,
      "lon": 5.36295661961305,
      "email": "post@easyconnect.no",
      "nace_1": "63.120",
      "nacetitle_1": "Drift av web-portaler",
      "orgno": "981176553",
      "website": "http://www.easyconnect.no/",
      "more": {
        "listings_on_address": "/listings/address?houseno=10&letter=&street_id=120133828",
      }
    }
  ]
}

2.1.3 /listings/address

Search for directory listings by address.

Parameter Data type Required Description
street string Either street or street_id Street name
street_id string Either street or street_id Street ID
page integer false The pagination index.
zip string false Filter results by postal code.
city string false Filter results by postal city.
municipality_code string false Filter results by municipality code (kommunenr.).
county_code string false Filter results by county code (fylkesnr.).
houseno integer false Filter results by house number.
letter string false Filter results by house letter (bokstav i husnr.).
sector string false Filter results by sector (business or consumer).

Returns a Listing search results response structure.

Example: /listings/address?street=Midtunhaugen&houseno=10&zip=52244

2.1.4 /listings/search_suggestions

Lists suggestions for alternative search terms, most useful if a full text search did not return any hits.

Example: /listings/search_suggestions?fulltext=eazy%20conect5

GET /listings/search_suggestions?fulltext=eazy%20conect HTTP/1.1
Host: api.easyconnect.no
Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "search_suggestions": [
    "Easy Connect AS",
    "Eazycom AS",
    "Care Connect AS"
  ]
}

2.1.5 /listings/{link}

Fetches a single listing by it's link attribute.

Returns a Listing response structure on success, if no listing with that link attribute exists it returns 404.

Example: /listings/Easy-Connect-AS6

GET /listings/Easy-Connect-AS HTTP/1.1
Host: api.easyconnect.no
Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "listing": {
    "sector": "business",
    "link": "Easy-Connect-AS",
    "displayname": "Easy Connect AS",
    "telenumbers": [
      {
        "usage_type": "normal",
        "terminal_type": "phone",
        "number": "53205300"
      }
    ],
    "street": "Midtunhaugen",
    "houseno": 10,
    "zip": "5224",
    "city": "Nesttun",
    "municipality": "Bergen",
    "county": "Hordaland",
    "street_id": "120133828",
    "municipality_code": "1201",
    "county_code": "12",
    "geoquality": "A",
    "displayaddress": "Midtunhaugen 10, 5224 Nesttun",
    "lat": 60.3189882162208,
    "lon": 5.36295661961305,
    "email": "post@easyconnect.no",
    "nace_1": "63.120",
    "nacetitle_1": "Drift av web-portaler",
    "orgno": "981176553",
    "website": "http://www.easyconnect.no/",
    "more": {
      "listings_on_address": "/listings/address?houseno=10&letter=&street_id=120133828"
    }
  }
}

Example: /listings/foobar7

GET /listings/foobar HTTP/1.1
Host: api.easyconnect.no
Authorization: Basic ZGVtbzozNTA1Y2VlOWY5ZDM0YjRiYWY1OWJmNjBkYmIwZjlkNQ==

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error":"Not found."
}

2.2 Response structures

2.2.1 Listing search results

All the listings search endpoints have a common response format:

  • result_size

    Integer

    The total number of results. This is not limited to the pagination limit, so the number of listings returned can be less than this.

  • page_size

    Integer, defaults to 20

    The listings APIs are paginated and return a maximum number of results per call.

    The actual number of returned listings is the smaller of page_size and result_size.

  • next_page

    URL

    The URL to fetch the next page of results.

  • listings

    Array of listings

    The actual results. See the listing documentation below.

  • more/search_suggestions

    URL

    For full text searches this is a URL to the listings/search_suggestions endpoint for this full text search.

2.2.2 Listing

  • sector

    String: ``business'' or ``consumer''

  • displayname

    String

    For sector=consumer this contains the persons full name. For sector=business this is the marketing name (if any) or legal name.

  • displaynamesub

    String

    For sector=business this contains the legal name or any other secondary name.

  • telenumbers

    Array of telenumbers

    Contains the phone numbers with metadata. See the Telenumber documentation below.

  • email

    String

    The company contact email address. Only used for sector=business.

  • website

    String

    URL to company website. Only used for sector=business.

  • nace_1

    String

    NACE code 1 (SN/SIC 2007)8.

  • nacetitle_1

    String

    Description/name of the code in nace_1.

  • orgno

    String (9 digits)

    Organization number from the national business registry.

  • displayaddress

    String

    Address (street, house number, postal code etc) as a single string for easy display to end users.

  • street

    String

    Address: Street. Can also contain other address parts like c/o or complete foreign addresses.

  • street_id

    String

    Address: Street ID.

  • houseno

    Int

    Address: House number.

  • letter

    String

    Address: House letter. E.g. «B» in Storgata 1B.

  • zip

    String

    Address: Post code.

  • city

    String

    Address: City (poststed).

  • municipality_code

    String

    Address: Municipality code (kommunenummer). We use an extended municipality code definition from SSB that also includes regional special codes9.

  • municipality

    String

    Address: Municipality name.

  • county_code

    String

    Address: County code (fylkesnummer). We use an extended municipality code definition from SSB that also includes regional special codes9.

  • county

    String

    Address: County name.

  • lat

    Floating point

    Latitude. Coordinates are given in EPSG:4326, WGS 84 planar coordinates.

  • lon

    Floating point

    Longitude.

  • geoquality

    String

    Level of address standardization.

    A
    Address match, coordinate points to an address from the cadastre.
    S
    Street match, coordinate of a constructed point central to the street.
    L
    Location match, coordinate is from the Central Register of Place Names (SSR)
    Z
    Zip match, coordinate of a constructed point in the center of the postal code area.
    M
    Municipality match, coordinate points at administrative centre.
    U
    No match against official Norwegian address data

2.2.3 Telenumber

This is an extensible format for phone numbers with extra metadata where each entry contains the following fields:

  • number The phone number. Norwegian numbers are represented without any

country prefix, any non-norwegian numbers that are present is returned in full E.164 format with + prefix.

  • usage_type
    • normal
    • subnumber
    • switchboard
    • data
  • terminal_type
    • ip
    • landline
    • phone generic fallback when no more specific information is available
    • mobile
    • fax
  • Example 1: Company contact number
{
  "number": "53205300",
  "usage_type": "normal",
  "terminal_type": "phone"
}
  • Example 2: Mobile phone
{
  "number": "47041198",
  "usage_type": "normal",
  "terminal_type": "phone"
}
  • Example 3: Fax
{
  "number": "67892432",
  "usage_type": "normal",
  "terminal_type": "fax"
}
  • Example 3: International number
{
  "number": "+46123456789",
  "usage_type": "normal",
  "terminal_type": "phone"
}

3 Document version

Version: 926a6 2018-12-11

Footnotes: