Hoppa till huvudsakligt innehåll

Teknisk beskrivning

Gränssnittsdefinition

Åtkomstpunkt

Verifiering: https://api-ver.lantmateriet.se/distribution/produkter/ortnamn/v2.1

Produktion: https://api.lantmateriet.se/distribution/produkter/ortnamn/v2.1

Schema

XML: http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1/ortnamn-2.1.1.xsd

JSON: http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1/ortnamn-2.1.1.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:

ReferenssystemSRID
SWEREF 99 TM3006
SWEREF 99 12 003007
SWEREF 99 13 303008
SWEREF 99 14 153012
SWEREF 99 15 003009
SWEREF 99 15 453013
SWEREF 99 16 303010
SWEREF 99 17 153014
SWEREF 99 18 003011
SWEREF 99 18 453015
SWEREF 99 20 153016
SWEREF 99 21 453017
SWEREF 99 23 153018

Felmeddelande

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

Sammanfattning

Ortnamn

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

OperationBeskrivning
GET /{id}
Hämta ett ortnamn med id.
POST /Hämta en eller flera ortnamn med id.
GET /kriterierHämta ett eller flera ortnamn m.h.a komplex filtrering.

Referens

Hämta referenser till ortnamn med angivet namn.

OperationBeskrivning
GET /referens/fritextHitta referens till ett ortnamn med ett namn.

Hälsokontroll

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

OperationBeskrivning
GET /healthHälsokontroll.

Operationer

GET /{id}

Beskrivning

Hämta ett ortnamn.

Exempel

/3541911

Requestparametrar
NamnBeskrivningTypDatatypObligatorisk
idOrtnamnets identitet.pathstringja
sridReferenssystem för geometrier. Default: 3006.queryintegernej
Svar

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


 

POST /

Beskrivning

Hämta en eller flera ortnamn med id. 250 olika identiteter kan skickas in i samma fråga.

Exempel
Body, Content-Type: application/xml
<IdRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1">
  <id>3541911</id>
  <id>3541913</id>
</IdRequest>


Body, Content-Type: application/json
[3541911, 3541913]
Requestparametrar

Body:

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

NamnBeskrivningTypDatatypObligatorisk
sridReferenssystem för geometrier. Default: 3006.queryintegernej
Svar

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


 

GET /kriterier

Beskrivning

Hämta ett eller flera ortnamn m.h.a. komplex filtrering. Minst en av parametrarna namn eller punkt måste anges.

För att hämta flera träffar än vad maxHits tillåter kan upprepade frågor ställas där parametern offset används för att förskjuta resultatet. När antalet ortnamn i svaret skiljer sig från maxHits finns det inga ortnamn kvar att hämta med givna parametrar.

Anges parametern punkt hämtas alltid endast den träff som ligger närmast punkten.

Exempel

/kriterier?namn=Arv&match=startsWith&sprak=Svenska&lankod=05&namntyp=Tätort&maxHits=1

Exempel med punkt

/kriterier?namn=Arv&punkt=7281695,674590&punktSrid=3006

Exempel med offset

Fråga 1: /kriterier?namn=Arv&match=startsWith&maxHits=100&offset=0

(svar med 100 ortnamn)

Fråga 2: /kriterier?namn=Arv&match=startsWith&maxHits=100&offset=100

(svar med 100 ortnamn)

Fråga 3: /kriterier?namn=Arv&match=startsWith&maxHits=100&offset=200

(svar med 50 ortnamn)

Totalt 250 ortnamn.

Requestparametrar
NamnBeskrivningTypDatatypObligatorisk
namnEn under en viss tid och en viss krets av människor entydig benämning på en viss geografisk lokalitet.querystringnej
matchInnehåller följande matchningar: startsWith, equals, endsWith, contains. Default equals.querystring (x ∈ { "contains", "equals", "endsWith", "startsWith" }) nej
punktAnges för att endast hämta den träff som ligger närmast angiven punkt, i formatet N,E där N anger koordinatens position i nordlig riktning och E anger koordinatens position i östlig riktning.querydoublenej
punktSridPunktens referenssystem. Obligatorisk för punktsökningar.queryintegernej
sprakOrtnamnets språktillhörighet, till exempel Svenska, Finska, Lulesamiska, Nordsamiska, Sydsamiska, Umesamiska.querystring (x ∈ { "Svenska", "Umesamiska", "Lulesamiska", "Nordsamiska", "Sydsamiska", "Tornedalsfinska", "Finska" })nej
lankodLänskod, tvåsiffrig kod enligt Rikets indelningar. Får ej kombineras med kommunkod.querystringnej
kommunkodKommunkod, fyrsiffrig kod enligt Rikets indelningar. Får ej kombineras med lankod.querystringnej
namntypEn eller flera typer av ortnamn som skall inkluderas i sökningen avser det objekt som ortnamnet syftar på, t.ex. naturobjekt, bebyggelse, fornlämning osv.querystring[] (x ∈ { "Tätort", "Bebyggelse", "Kyrka", "Fornlämning", "Anläggning", "Glaciär", "Sankmark", "Vattendelsområde", "Natur- och terrängnamn","Vattendrag","Trakt", "Hav och sjö" , "Naturvårdsområde" })nej
maxHitsMax antal träffar som tjänsten ska svara med. Default 100. Max 400queryintegernej
offset

Första posten i resultatet som tjänsten ska svara med.

queryintegernej
sridReferenssystem för geometrier. Default: 3006 .queryintegernej
Svar

Ett OrtnamnResponse i form av en JSON-array eller GML-lista med ortnamn, beroende på vilket format som efterfrågades.


 

GET /referens/fritext

Beskrivning

Hämta referenser till ortnamn med angivet namn.

Exempel

/referens/fritext?namn=Arv&match=similar

Requestparametrar
NamnBeskrivningTypDatatypObligatorisk
namnEn under en viss tid och en viss krets av människor entydig benämning på en viss geografisk lokalitetquerystringja
matchInnehåller följande matchningar: startsWith, equals, endsWith, contains, similar. Default similar.querystring  (x ∈ { "contains", "equals", "endsWith", "startsWith", "similar" })nej
lankodLänskod, tvåsiffrig kod enligt Rikets indelningar. Får ej kombineras med kommunkod.querystringnej
kommunkodKommunkod, fyrsiffrig kod enligt Rikets indelningar. Får ej kombineras med lankod.querystringnej
maxHitsKan användas för att begränsa antal resultat. Default 100. Max 400.queryintegernej
Svar

Ett OrtnamnsreferensResponse i form av en JSON-array eller XML-lista med ortnamnsreferenser, 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 ortnamn med angiven identifierare. 250 olika identiteter kan anges i en fråga.

Properties
NamnBeskrivningTypMultiplicitet
idOrtnamns identitet.string1..*
Exempel
XML
<IdRequest
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1">
  <id>3541911</id>
  <id>3541913</id>
</IdRequest>
JSON
["3541911", "3541913"]


Svar

OrtnamnResponse

Behållare för sökningens resultat - ingen, en eller flera sökträffar av typen Ortnamn.


NamnBeskrivningTypMultiplicitet
totaltAntalAttribut som anger totalt antal träffar sökningen kan resultera iinteger1
OrtnamnOrtnamnOrtnamn0..*


XML
<OrtnamnResponse
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1" gml:id="response" totaltAntal="2">
  <gml:boundedBy>
    <gml:Envelope srsName="urn:ogc:def:crs:EPSG::3006">
      <gml:lowerCorner>6464377.0 440597.0</gml:lowerCorner>
      <gml:upperCorner>7282166.0 674695.0</gml:upperCorner>
    </gml:Envelope>
  </gml:boundedBy>
  <OrtnamnMember>
    <Ortnamn gml:id="ID_3541911">
      ...
    </Ortnamn>
  </OrtnamnMember>
  <OrtnamnMember>
    <Ortnamn gml:id="ID_3541913">
      ...
    </Ortnamn>
  </OrtnamnMember>
</OrtnamnResponse>


JSON
{
  "type": "FeatureCollection",
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:EPSG::3006"
    }
  },
  "bbox": [
    692839.0,
    7281385.0,
    692839.0,
    7281385.0
  ],
  "totaltAntal": 1,
  "features": [
    {
      "type": "Feature",
      "bbox": [
        692839.0,
        7281385.0,
        692839.0,
        7281385.0
      ],
      "id": "3440005",
      ...
    }
  ]
}


Ortnamn

Properties
NamnTypMultiplicitet
idstring1
namnstring1
sprakstring (x ∈ { "Svenska", "Umesamiska", "Lulesamiska", "Nordsamiska", "Sydsamiska", "Tornedalsfinska", "Finska" })1
PlaceringPlacering0..*
Exempel
XML
<Ortnamn gml:id="ID_3440005">
   <gml:boundedBy>
      <gml:Envelope srsName="urn:ogc:def:crs:EPSG::3006">
         <gml:lowerCorner>7281385.0 692839.0</gml:lowerCorner>
         <gml:upperCorner>7281385.0 692839.0</gml:upperCorner>
      </gml:Envelope>
   </gml:boundedBy>
   <id>3440005</id>
   <namn>Arvidsjaur</namn>
   <sprak>Svenska</sprak>
   <Placering>
      ...
   </Placering>
   <Placering>
      ...
   </Placering>
</Ortnamn>
JSON
{
  "type" : "Feature",
  "bbox" : [ 7.0, 6.0, 8.0, 7.0 ],
  "id" : "2",
  "geometry" : null,
  "properties" : {
    "id" : 2,
    "namn" : "namn2",
    "sprak" : "Lulesamiska",
    "placering" : [
      ...
    ]
  }
}


Placering

Properties

Namn

Typ

Multiplicitet

lankodstring1
lannamnstring1
kommunkodstring 1
kommunnamnstring1
sockenstadkodstring1
sockenstadnamnstring1
namntypstring (x ∈ { "Tätort", "Bebyggelse", "Kyrka", "Fornlämning", "Anläggning", "Glaciär", "Sankmark", "Vattendelsområde", "Natur- och terrängnamn", "Vattendrag", "Trakt", "Hav och sjö" , "Naturvårdsområde" })1
punktpunkt1
Exempel


XML


XML
<Placering>
   <lankod>25</lankod>
   <lannamn>Norrbotten</lannamn>
   <kommunkod>2505</kommunkod>
   <kommunnamn>Arvidsjaur</kommunnamn>
   <sockenstadkod>0161</sockenstadkod>
   <sockenstadnamn>Arvidsjaur</sockenstadnamn>
   <namntyp>Tätort</namntyp>
   <Punkt>
      <gml:Point srsName="urn:ogc:def:crs:EPSG::3006" gml:id="GM_177">
         <gml:pos>7281385.0 692839.0</gml:pos>
      </gml:Point>
   </Punkt>
</Placering>


JSON

JSON
{
   "lankod": "25",
   "lannamn": "Norrbotten",
   "kommunkod": "2505",
   "kommunnamn": "Arvidsjaur",
   "sockenstadkod": "0161",
   "sockenstadnamn": "Arvidsjaur",
   "namntyp": "Tätort",
   "punkt": {
       "coordinates": [
          692839,
          7281385
          ],
       "type": "Point"
    }
}




OrtnamnsreferensResponse

Behållare för sökningens resultat - ingen, en eller flera sökträffar av typen Ortnamnsreferens.

Properties
NamnTypMultiplicitet
Ortnamnsreferens Ortnamnsreferens 0..*
Exempel

XML

XML
<OrtnamnsreferensResponse
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/ortnamn/v2.1">
  <Ortnamnsreferens>
    <id>3541911</id>
    <namn>Dunberg</namn>
  </Ortnamnsreferens>
  <Ortnamnsreferens>
    <id>3541912</id>
    <namn>Dunberg</namn>
  </Ortnamnsreferens>
</OrtnamnsreferensResponse>

JSON

JSON
[
  {
    "id": "3541911",
    "namn": "Dunberg"
  },
  {
    "id": "3541912",
    "namn": "Dunberg"
  }
]



Ortnamnsreferens

Properties
NamnTypMultiplicitet
idstring1
namnstring1
Exempel

XML

XML
<Ortnamnsreferens>
  <id>3541911</id>
  <namn>Dunberg</namn>
</Ortnamnsreferens>

JSON

JSON
{
  "id": "3541911",
  "namn": "Dunberg"
}



HealthResponse

Anger status för tjänsten.

Properties
NamnTypMultiplicitet
upboolean1
Exempel

JSON

JSON
{
  "up": true
}


Felmeddelande

Fault

Properties
NamnBeskrivningTypMultiplicitet
codeHTTP-felkod.integer1
reasonTextöversättning av felkodstring1
errorsMer detaljerad felbeskrivningstring0..*
Exempel
XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Fault
    xmlns="http://namespace.lantmateriet.se/distribution/produkter/fault/v1">
  <code>400</code>
  <reason>Bad Request</reason>
  <errors>Namn field is empty!</errors>
</Fault>
JSON
{
  "code": 400,
  "reason": "Bad Request",
  "errors": [
    "Namn field is empty!"
  ]
}