Gränssnittsdefinition

Åtkomstpunkt

Verifiering: https://api-ver.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2

Produktion: https://api.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2

Schema


XML: http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2/belagenhetsadress-4.2.2.xsd

JSON: http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2/belagenhetsadress-4.2.2.json

Format

Data kan hämtas i XML- och JSON-format. Vilket format som önskas anges i HTTP-headern Accept med värdena application/xml eller application/json. I frågor som skickas in med POST ska motsvarande värden anges i headern Content-Type.

Referenssystem

I frågor som accepterar eller svarar med geometrier stöds följande referenssystem:

Referenssystem

SRID

SWEREF 99 TM

3006

SWEREF 99 12 00

3007

SWEREF 99 13 30

3008

SWEREF 99 14 15

3012

SWEREF 99 15 00

3009

SWEREF 99 15 45

3013

SWEREF 99 16 30

3010

SWEREF 99 17 15

3014

SWEREF 99 18 00

3011

SWEREF 99 18 45

3015

SWEREF 99 20 15

3016

SWEREF 99 21 45

3017

SWEREF 99 23 15

3018

Felmeddelande

Om ett fel uppstår skickas ett svar med en HTTP-felkod och ett Fault-meddelande.

Sammanfattning

Adress

Hämta hela - eller delmängder av - adresser.

Operation

Beskrivning

GET /{id}

Hämta en adress med id.

POST /

Hämta en eller flera adresser med id.

GET /registerenhet/{id}

Hämta en eller flera adresser med registerenhetsid.

POST /registerenhet

Hämta en eller flera adresser med registerenhetsid.

GET /punkt

Hämta närmaste adress med koordinat.

Referens

Hämta referenser till adresser, med etikett och id.

Operation

Beskrivning

GET /referens/fritext

Hitta adresser med en fritextsökning.

POST /referens/geometri

Hitta adresser med en geometri.

Autocomplete

För användning av autocompletefunktioner. Hämtar stegvis adressbeteckningar och slutligen en adressreferens, allteftersom söktexten fylls i.

Operation

Beskrivning

GET /autocomplete/adress

Autocompletefunktion för att hitta adresser.

GET /autocomplete/referens

Hämtar adressreferens från dess fulla autocompletetext.

Hälsokontroll

För att kolla om tjänsten är uppe och mår bra.

Operation

Beskrivning

GET /health

Hälsokontroll.

Operationer

GET /{id}

Beskrivning

Hämta en adress med id. Delar av adressen kan hämtas genom includeData-parametern.

Exempel

/12345678-1234-1234-1234-123456789012?includeData=total&srid=3006

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

id

Adressens objektidentitet.

path

string (uuid)

ja

includeData

Vad i adressen som ska hämtas. Flera delmängder kan anges som en kommaseparerad lista. Som default hämtas ingenting. Möjliga värden:

  • basinformation - allt utom berörkretsen.
  • berorkrets - registerenheten.
  • total - allt.

query

string[] (x ∈ { "basinformation", "berorkrets", "total" })

nej

srid

Referenssystem för geometrier. Default: 3006.

query

integer

nej

Svar

Ett BelagenhetsadressResponse i form av en GeoJSON eller GML FeatureCollection med adresser, beroende på vilket format som efterfrågades.



POST /

Beskrivning

Hämta en eller flera adresser med id. 250 id:n kan skickas in i samma fråga. Delar av adressen kan hämtas genom includeData-parametern.

Exempel

/?includeData=total

Body, Content-Type: application/xml
<IdRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2">
  <id>12345678-1234-1234-1234-123456789012</id>
  <id>10000008-cafe-cafe-cafe-100000000002</id>
</IdRequest>
Body, Content-Type: application/json
["12345678-1234-1234-1234-123456789012", "10000008-cafe-cafe-cafe-100000000002"]

Requestparametrar

Body: IdRequest - ett objekt innehållande en lista med objektidentiteter.

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

includeData

Vad i adressen som ska hämtas. Flera delmängder kan anges som en kommaseparerad lista. Som default hämtas ingenting. Möjliga värden:

  • basinformation - allt utom berörkretsen.
  • berorkrets - registerenheten.
  • total - allt.

query

string[] (x ∈ { "basinformation", "berorkrets", "total" })

nej

srid

Referenssystem för geometrier. Default: 3006.

query

integer

nej

Svar

Ett BelagenhetsadressResponse i form av en GeoJSON eller GML FeatureCollection med adresser, beroende på vilket format som efterfrågades.



GET /registerenhet/{id}

Beskrivning

Hämta en eller flera adresser med en registerenhets objektidentitet. Delar av adressen kan hämtas genom includeData-parametern.

Exempel

/registerenhet/12345678-1234-1234-1234-123456789012?includeData=total

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

id

Registerenhetens id i form av ett UUID.

path

string (uuid)

ja

includeData

Vad i adressen som ska hämtas. Flera delmängder kan anges som en kommaseparerad lista. Som default hämtas ingenting. Möjliga värden:

  • basinformation - allt utom berörkretsen.
  • berorkrets - registerenheter.
  • total - allt.

query

string[] (x ∈ { "basinformation", "berorkrets", "total" })

nej

srid

Referenssystem för geometrier. Default: 3006.

query

integer

nej

Svar

Ett BelagenhetsadressResponse i form av en GeoJSON eller GML FeatureCollection med adresser, beroende på vilket format som efterfrågades.



POST /registerenhet

Beskrivning

Hämta en eller flera adresser med en eller flera registerenheters objektidentitet. 250 id:n kan skickas in i samma fråga. Delar av adressen kan hämtas genom includeData-parametern.

Exempel

/registerenhet?includeData=basinformation

Body, Content-Type: application/xml
<IdRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2">
  <id>12345678-1234-1234-1234-123456789012</id>
  <id>10000008-cafe-cafe-cafe-100000000002</id>
</IdRequest>
Body, Content-Type: application/json
["12345678-1234-1234-1234-123456789012", "10000008-cafe-cafe-cafe-100000000002"]

Requestparametrar

Body: IdRequest - ett objekt innehållande en lista med objektidentiteter.

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

includeData

Vad i adressen som ska hämtas. Flera delmängder kan anges som en kommaseparerad lista. Som default hämtas ingenting. Möjliga värden:

  • basinformation - allt utom berörkretsen.
  • berorkrets - registerenheten.
  • total - allt.

query

string[] (x ∈ { "basinformation", "berorkrets", "total" })

nej

srid

Referenssystem för geometrier. Default: 3006.

query

integer

nej

Svar

Ett BelagenhetsadressResponse i form av en GeoJSON eller GML FeatureCollection med adresser, beroende på vilket format som efterfrågades.



GET /punkt

Beskrivning

Hämtar den adress som ligger närmast angiven punkt. Delar av adressen kan hämtas genom includeData-parametern.

Exempel

/punkt?punktSrid=3006&koordinater=6728782.15,616919.80&includeData=basinformation,berorkrets&srid=3006

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

punktSrid

Vilket referenssystem punkten anges i. Default: 3006.

query

integer

nej

koordinater

Punktens koordinater, enligt ordningen northing, easting, separerade med ett kommatecken.

query

decimal

ja

includeData

Vad i adressen som ska hämtas. Flera delmängder kan anges som en kommaseparerad lista. Som default hämtas ingenting. Möjliga värden:

  • basinformation - allt utom berörkretsen.
  • berorkrets - registerenheter.
  • total - allt.

query

string[] (x ∈ { "basinformation", "berorkrets", "total" })

nej

srid

Referenssystem för geometrier. Default: 3006.

query

integer

nej

Svar

Ett BelagenhetsadressResponse i form av en GeoJSON eller GML FeatureCollection med adresser, beroende på vilket format som efterfrågades.



GET /referens/fritext

Beskrivning

Hämta referenser till adresser genom en sökning på adressbeteckningen.

Exempel

/referens/fritext?adress=lantmäterig 2 gävle&maxHits=15

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

adress

En söksträng med 3 - 300 tecken.

query

string

ja

kommunkod

Kommunkod, fyrsiffrig kod enligt Rikets indelningar.

query

string

nej

status

Filtrera på belägenhetsadresstatus.

query

string[] (x ∈ { "Gällande", "Reserverad" })

nej

maxHits

Kan användas för att begränsa antal resultat. Max 500, default 100.

query

integer

nej

splitAdress

Om värdet är true populeras AdressComponents i svaret. Default false.

query

boolean

nej

Svar

Ett BelagenhetsadressreferensResponse i form av en JSON-array eller XML-lista med adressreferenser, beroende på vilket format som efterfrågades.



POST /referens/geometri

Beskrivning

Hämta referenser till adresser inom en given geometri.

Exempel

/referens/geometri

Body, Content-Type: application/xml
<GeometriRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2">
  <Geometri>
    <gml:Polygon gml:id="ID_8" srsName="urn:ogc:def:crs:EPSG::3006"
        xmlns:gml="http://www.opengis.net/gml/3.2">
      <gml:exterior>
        <gml:LinearRing>
          <gml:posList>6728548 618174 6728423 618153 6728395 618270 6728525 618296 6728548 618174</gml:posList>
        </gml:LinearRing>
      </gml:exterior>
    </gml:Polygon>
  </Geometri>
  <buffer>50</buffer>
</GeometriRequest>
Body, Content-Type: application/json
{
  "geometri": {
    "type": "Polygon",
    "crs": {
      "type": "name",
      "properties": {
        "name": "urn:ogc:def:crs:EPSG::3006"
      }
    },
    "coordinates": [
      [ [618174, 6728548], [618153, 6728423], [618270, 6728395],
        [618296, 6728525], [618174, 6728548] ]
    ]
  },
  "buffer": 50
}

Requestparametrar

Body: GeometriRequest - ett objekt innehållande en geometri i GeoJSON- eller GML-format och eventuellt attributet buffer som kan användas för att utöka området runt geometrin.

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

status

Filtrera på belägenhetsadresstatus.

query

string[] (x ∈ { "Gällande", "Reserverad" })

nej

splitAdress

Om värdet är true populeras AdressComponents i svaret. Default false.

query

boolean

nej

Svar

Ett BelagenhetsadressreferensResponse i form av en JSON-array eller XML-lista med adressreferenser, beroende på vilket format som efterfrågades.



GET /autocomplete/adress

Beskrivning

För användning av autocompletefunktioner. Hämtar stegvis adresser allteftersom söktexten fylls i.

Den stegvisa sökningen funkar på följande vis:

Beteckning

Resultat

(tom)

Alla kommuner

"g"

Alla kommuner som börjar på g

"gävle " (med mellanslag på slutet)

Alla adressområden i Gävle

"gävle la"

Alla adressområden i Gävle som börjar på la

"gävle lantmäterigatan " (med mellanslag på slutet)

Alla adressplatser på Lantmäterigatan i Gävle

"gävle lantmäterigatan 2"

Alla adressplatser på Lantmäterigatan i Gävle som börjar med 2

"gävle lantmäterigatan 2b" till GET /autocomplete/referens

Adressreferens till Gävle Lantmäterigatan 2B

Exempel

/autocomplete/adress

/autocomplete/adress?adress=gävle lantmäterigatan &maxHits=20

/autocomplete/adress?adress=gävle lantmäterigatan 2b

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

adress

Adressbeteckning i ordningen <kommun>, <adressområde>, <adressplats>

query

string

nej

status

Filtrera på belägenhetsadresstatus.

query

string[] (x ∈ { "Gällande", "Reserverad" })

nej

maxHits

Kan användas för att begränsa svaret. Ange ett värde mindre eller lika med 0 för obegränsat antal. Default 100.

query

integer

nej

Svar

Ett AutocompleteResponse i form av en JSON-array eller XML-lista med delar av adresser, beroende på vilket format som efterfrågades.



GET /autocomplete/referens

Beskrivning

För användning av autocompletefunktioner. Hämta referenser till adresser från dess fulla autocompletetext.

Exempel

/autocomplete/referens?adress=gävle lantmäterigatan 2b

Requestparametrar

Namn

Beskrivning

Typ

Datatyp

Obligatorisk

adress

En söksträng med 3 - 300 tecken.

query

string

ja

status

Filtrera på belägenhetsadresstatus.

query

string[] (x ∈ { "Gällande", "Reserverad" })

nej

maxHits

Kan användas för att begränsa antal resultat. Max 500, default 100.

query

integer

nej

splitAdress

Om värdet är true populeras AdressComponents i svaret. Default false.

query

boolean

nej

Svar

Ett BelagenhetsadressreferensResponse i form av en JSON-array eller XML-lista med adressreferenser, beroende på vilket format som efterfrågades.


 

GET /health

Beskrivning

För att kolla om tjänsten är uppe och mår bra.

Exempel

/health

Svar

Ett HealthResponse i form av ett JSON-objekt som anger tjänstens status. OBS! Denna fråga har ingen XML-variant.


Datatyper

Frågor

IdRequest

Hämta adress med angiven identifierare. 250 idn kan anges i en fråga.

Properties

Namn

Beskrivning

Typ

Multiplicitet

id

Adressens objektidentitet.

string (uuid)

1..*
Exempel
XML
<IdRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2">
  <id>12345678-1234-1234-1234-123456789012</id>
  <id>10000008-cafe-cafe-cafe-100000000002</id>
</IdRequest>
JSON
["12345678-1234-1234-1234-123456789012", "10000008-cafe-cafe-cafe-100000000002"]



GeometriRequest

Hitta adress inom geometri. Vissa begränsningar finns:

Begränsning

Maxvärde

Antal punkter i en MultiPoint.

1 000 st

Antal brytpunkter i en LineString eller MultiCurve.

1 000 st

Antal brytpunkter i en Polygon eller MultiSurface.

1 000 st

Längd på en LineString eller sammanlagd längd på en MultiCurve.

100 000 m

Area för en Polygon eller sammanlagd area för en MultiSurface.

1 000 000 m 2

Omkrets på en Polygon eller sammanlagd omkrets på en MultiSurface.

200 000 m
Properties

Namn

Beskrivning

Typ

Multiplicitet

Geometri

En GML- eller GeoJSON-geometri. GML-geometrier ska följa Lantmäteriets GML 3.2.1-profil.

geometri

1

buffer

Område runt den angivna geometrin som ska ingå i sökträffen.

integer

0..1
Exempel
XML
<GeometriRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/belagenhetsadress/v4.2">
  <Geometri>
    <gml:Polygon gml:id="ID_8" srsName="urn:ogc:def:crs:EPSG::3006"
        xmlns:gml="http://www.opengis.net/gml/3.2">
      <gml:exterior>
        <gml:LinearRing>
          <gml:posList>6728548 618174 6728423 618153 6728395 618270 6728525 618296 6728548 618174</gml:posList>
        </gml:LinearRing>
      </gml:exterior>
    </gml:Polygon>
  </Geometri>
  <buffer>50</buffer>
</GeometriRequest>
JSON
{
  "geometri": {
    "type": "Polygon",
    "crs": {
      "type": "name",
      "properties": {
        "name": "urn:ogc:def:crs:EPSG::3006"
      }
    },
    "coordinates": [
      [ [618174, 6728548], [618153, 6728423], [618270, 6728395],
        [618296, 6728525], [618174, 6728548] ]
    ]
  },
  "buffer": 50
}



HealthResponse

Anger status för tjänsten.

Properties

Namn

Typ

Multiplicitet

up

boolean

1
Exempel
JSON
{
  "up": true
}

Felmeddelande

Fault

Properties

Namn

Beskrivning

Typ

Multiplicitet

code

HTTP-felkod.

integer

1

reason

Textöversättning av felkod

string

1

errors

Mer detaljerad felbeskrivning

string

0..*
Exempel
XML
<Fault
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/fault/v1">
  <code>400</code>
  <reason>Bad Request</reason>
  <errors>Area is too large! Max is 1000000 - area is 1048076</errors>
</Fault>
JSON
{
   "code": 400,
   "reason": "Bad Request",
   "errors": [
      "Area is too large! Max is 1000000 - area is 1048076"
   ]
}