API Documentation

General points

  • HTTP REST API
  • JSON format of request and response
  • Host: https://api.hittaid.se

Authentication

Authentication is performed via HTTP Basic Auth, login and password are account-specific and are sent to each individual partner. Please, contact us at api@hittaid.se to obtain your credentials.

Endpoints

HittaID API has two endpoints, both of them produce the same result, the difference is in essence of input data - postal code or address string.

1. Lookup by postal code

POST /lookup/postal_code

Request format

Attribute Description
postal_code R Valid Swedish postal code in NNNNN format. For example, 46153 or 11134
  • If postal code is not valid, 404 error response will be returned

Response format

Attribute Description
category_id Number of region, from 1 to 4. This value corresponds to SE1, SE2, SE3 or SE4 Sweden region
handle 3-letter identifier of area
name Area name, usually corresponds to the main city in area
cable_owner Information about cable owner of the area (referred as Company below)
cable_owner.name Company name
cable_owner.legal_form Legal form of Company (AB, KB, ek för)
cable_owner.organisation_number Organisation number of Company
cable_owner.website Website of Company
cable_owner.city -
cable_owner.postal_code -
cable_owner.address_line -
cable_owner.email -
cable_owner.phone -
cable_owner.description -
cable_owner.infrastructure_type Typ av ledningar
cable_owner.geo_area Län
cable_owner.municipalities Tillhörande kommuner

Request example

curl --location --request POST 'https://api.hittaid.se/lookup/postal_code' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Basic ZXhhbXBsZUxvZ2luOmV4YW1wbGVQYXNzd29yZA==' \
      --data-raw '{
      "postal_code": "46153"
      }'

Response example

{
  "data": {
    "handle": "TRH",
    "name": "Trollhättan",
    "cable_owner": {
      "name": "Trollhättan Energi Elnät",
      "legal_form": "AB",
      "organisation_number": "5561946921",
      "website": "www.trollhattanenergi.se",
      "city": "TROLLHÄTTAN",
      "postal_code": "46129",
      "address_line": "Box 933\n",
      "email": "kundservice@trollhattanenergi.se",
      "phone": "+4620899000",
      "description": "KoncernenTrollhättan Energi´s verksamhet består av fjärrvärme, vatten och avlopp, stadsnät, biogas samt eldistribution. Vi utför även ledningsanvisning för Trollhättan Stads gatubelyning.",
      "infrastructure_type": "Avlopp, Dagvatten, El, Elektronisk kommunikation, Fjärrvärme, Gas, Gatubelysning, Kulvert/tunnel/bergrum, Vatten",
      "geo_area": "Västra Götalands län",
      "municipalities": "Ale, Alingsås, Essunga, Grästorp, Lilla Edet, Mellerud, Trollhättan, Uddevalla, Vänersborg\n"
    },
    "category_id": 3
  }
}

2. Lookup by coordinates

POST /lookup/coordinates

Attribute Description
latitude R Latitude of address in numeric format, should be inside Sweden. For example, 58.2715013
longitude R Longitude of address, should be inside Sweden. For example, 12.2831262
  • Coordinates endpoint works good with Google Geocoder - user specifies the address, that is sent to Google Geocoder, it responds with coordinates, that are sent to this endpoint to trade them for area data
  • If provided coordinates are not valid, or the place is outside of Sweden, 404 error response with correspondent message will be returned

Response format

Attribute Description
category_id Number of region, from 1 to 4. This value corresponds to SE1, SE2, SE3 or SE4 Sweden region
handle 3-letter identifier of area
name Area name, usually corresponds to the main city in area
cable_owner Information about cable owner of the area (referred as Company below)
cable_owner.name Company name
cable_owner.legal_form Legal form of Company (AB, KB, ek för)
cable_owner.organisation_number Organisation number of Company
cable_owner.website Website of Company
cable_owner.city -
cable_owner.postal_code -
cable_owner.address_line -
cable_owner.email -
cable_owner.phone -
cable_owner.description -
cable_owner.infrastructure_type Typ av ledningar
cable_owner.geo_area Län
cable_owner.municipalities Tillhörande kommuner

Request example

curl --location --request POST 'http://api.hittaid.se/lookup/coordinates' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Basic ZXhhbXBsZUxvZ2luOmV4YW1wbGVQYXNzd29yZA==' \
      --data-raw '{
      "latitude": 58.2715013,
      "longitude": 12.2831262
        }'

Response example

{
  "data": {
    "handle": "TRH",
    "name": "Trollhättan",
    "cable_owner": {
      "name": "Trollhättan Energi Elnät",
      "legal_form": "AB",
      "organisation_number": "5561946921",
      "website": "www.trollhattanenergi.se",
      "city": "TROLLHÄTTAN",
      "postal_code": "46129",
      "address_line": "Box 933\n",
      "email": "kundservice@trollhattanenergi.se",
      "phone": "+4620899000",
      "description": "KoncernenTrollhättan Energi´s verksamhet består av fjärrvärme, vatten och avlopp, stadsnät, biogas samt eldistribution. Vi utför även ledningsanvisning för Trollhättan Stads gatubelyning.",
      "infrastructure_type": "Avlopp, Dagvatten, El, Elektronisk kommunikation, Fjärrvärme, Gas, Gatubelysning, Kulvert/tunnel/bergrum, Vatten",
      "geo_area": "Västra Götalands län",
      "municipalities": "Ale, Alingsås, Essunga, Grästorp, Lilla Edet, Mellerud, Trollhättan, Uddevalla, Vänersborg\n"
    },
    "category_id": 3
  }
}