• Intro
• Frågan
• Svaret
• Streaming
• Datamodell
• Versionshistorik

Så här kan en fråga exempelvis se ut:

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeObjectVersion" limit="10">
  <FILTER>
    <EQ name="SomeDataField" value="2" />
  </FILTER>
  </QUERY>
</REQUEST>

Frågan skickas med ett POST-anrop, publiceringspunktens filändelse avgör formatet på svaret.

I URLen definieras vilken version som ska användas och ändelsen (xml eller json) anger format på det returnerade svaret.
http://api.trafikinfo.trafikverket.se/v[version]/data.[format]

Tillgängliga URLer:
https://datacache-test.trafikverket.se/v2/data.xml
https://datacache-test.trafikverket.se/v2/data.json

<REQUEST/> omsluter frågan. Den måste innehålla <LOGIN/> och en eller flera <QUERY/>.

<LOGIN/> måste innehålla attributet authenticationkey där användarens unika nyckel anges. (Genom registrering fås tillgång till nycklar.)

<FILTER/> måste finns under <QUERY/>, även om inga filteroperatorer anges. Det är här som det specificeras vilket data som ska returneras. Det finns ett antal olika operatorer för att bygga ihop ett filter.

Operatorerna har två attribut:

(Operatorn <WITHIN/> kan även ha attributen shape och radius).

Operatorerna kan grupperas genom att de omsluts av följande:

{  
   User:{  
      Name:"User_1",
      Results:[  
         {  
            Product:"abc",
            Score:9
         },
         {  
            Product:"xyz",
            Score:5
         }
      ]
   }
}
{  
   User:{  
      Name:"User_2",
      Results:[  
         {  
            Product:"abc",
            Score:5
         },
         {  
            Product:"xyz",
            Score:7
         }
      ]
   }
}

<FILTER>
    <ELEMENTMATCH>
        <EQ name="User.Results.Product" value="abc" />
        <GT name="User.Results.Score" value="6" />
    </ELEMENTMATCH>
</FILTER>

{  
   User:{  
      Name:"User_1",
      Results:[  
         {  
            Product:"abc",  // Uppfyller Product='abc'
            Score:9         // Uppfyller Score>6
         },
         {  
            Product:"xyz",
            Score:5
         }
      ]
   }
}

<FILTER>
    <AND>
        <EQ name="User.Results.Product" value="abc" />
        <GT name="User.Results.Score" value="6" />
    </AND>
</FILTER>

{  
   User:{  
      Name:"User_1",
      Results:[  
         {  
            Product:"abc",  // Uppfyller Product='abc'
            Score:9         // Uppfyller Score>6
         },
         {  
            Product:"xyz",
            Score:5
         }
      ]
   }
}
{  
   User:{  
      Name:"User_2",
      Results:[  
         {  
            Product:"abc",  // Uppfyller Product='abc'
            Score:5
         },
         {  
            Product:"xyz",
            Score:7         // Uppfyller Score>6
         }
      ]
   }
}

{
    "RESPONSE": {
    "RESULT": [
        {
        "TrainAnnouncement": [
            {
            "ActivityId": "1",
            "ActivityType": "Avgang",
            "Advertised": true
            },
            {
            "ActivityId": "2",
            "ActivityType": "Avgang",
            "Advertised": false
            },
            {
            "ActivityId": "3",
            "ActivityType": "Ankomst",
            "Advertised": true
            },
            {
            "ActivityId": "4",
            "ActivityType": "Ankomst",
            "Advertised": false
            }
		]
	    }
	}
}
                

<FILTER>
    <NOT>
        <EQ name="ActivityType" value="Avgang" />
        <GT name="Advertised" value="true" />
    </NOT>
</FILTER>
                

   "RESPONSE": {
    "RESULT": [
        {
        "TrainAnnouncement": [
            {
            "ActivityId": "2",
            "ActivityType": "Avgang",
            "Advertised": false
            },
            {
            "ActivityId": "3",
            "ActivityType": "Ankomst",
            "Advertised": true
            },
            {
            "ActivityId": "4",
            "ActivityType": "Ankomst",
            "Advertised": false
            }
		]
	    }
	}
}
                

<FILTER>
    <NOT>
        <OR>
            <EQ name="ActivityType" value="Avgang" />
            <GT name="Advertised" value="true" />
        </OR>
    </NOT>
</FILTER>
                

{
    "RESPONSE": {
    "RESULT": [
        {
        "TrainAnnouncement": [
            {
            "ActivityId": "4",
            "ActivityType": "Ankomst",
            "Advertised": false
            }
		]
	    }
	}
}
                

Ett exempel på ett filter:

<FILTER>
    <OR>
        <AND>
            <EQ name="User.Name" value="kalle anka" />
            <IN name="User.Category" value="a, b, c" />
        </AND>
        <GT name="User.Number" value="133" />
    </OR>
</FILTER>

Ofta är bara en delmängd av data intressant, då är det önskvärt att bara få det aktuella datat med i svaret. Därför är det möjligt att ange vilka datafält som ska returneras, alternativt inte returneras.

<INCLUDE/> - anger ett datafält som ska inkluderas i svaret. Datafält som inte finns definierade kommer att exkluderas i svaret. INCLUDE-elementet kan förekomma inga, en eller många gånger. Elementets innehåll definierar datafältet. Fält som det görs sortering på (d.v.s. finns angivna i QUERY-attributet orderby) kommer också att inkluderas.
Exempel:

<QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <INCLUDE>WantedField</INCLUDE>
    <INCLUDE>WantedField2</INCLUDE>
</QUERY>

<EXCLUDE/> - anger ett datafält som ska exkluderas i svaret. Datafält som inte finns definierade kommer att inkluderas i svaret. EXCLUDE-elementet kan förekomma inga, en eller många gånger. Elementets innehåll definierar datafältet.
Exempel:

<QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <EXCLUDE>UnwantedField</EXCLUDE>
    <EXCLUDE>UnwantedField2</EXCLUDE>
</QUERY>

<DISTINCT/> - anger ett datafält vars unika värden ska returneras. Svaret innehåller en array med unika värden av det specificerade fältet. DISTINCT-elementet kan förekomma inga eller en gång. Elementets innehåll definierar datafältet.
Exempel:

<QUERY objecttype="SomeObjectType" schematversion="SomeSchemaVersion">
    <DISTINCT>DistinctField</DISTINCT>
</QUERY>

Enbart den ena av <INCLUDE/>, <EXCLUDE/> eller <DISTINCT/> kan av naturliga skäl defineras i en <QUERY/>.

Notera att alla attributvärden i datamodellen är skiftlägeskänsliga (case sensitive).

Datum och tider

En timespan definieras enligt d.hh:mm:ss (där ss är valfritt).

Ett dygn: "1.00:00"
En timme: "0.1:00"
En minut: "0.00:01"
En sekund: "0.00:00:01"
Två dygn och 10 timmar och 15 minuter: "2.10:15"
59 minuter: "0.00:59"
60 minuter: "0.01:00"
23 timmar: "0.23:00"
24 timmar: "1.00:00"

<GT name='AnnonseradTid' value='$dateadd(-0.00:15:00)' />

Funktioner

För att kunna köra beräkningar i APIet kan man exekvera funktioner från förbestämda funktionsbibliotek. Detta kan vara användbart då man skall göra beräkningar på informationsobjekt i APIet. Syntaxen för att exekvera funktioner i frågan ser ut enligt nedan:

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion" >
    <FILTER>
      <GT name="DataField" value="$function.SomeLib_v1.SomeMethod(param1, param2)" />
    </FILTER>
  </QUERY>
</REQUEST>

EVAL

<REQUEST>
    <LOGIN authenticationkey="SomeAuthenticationKey" />
    <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
        <EVAL alias="MyFirstFunctionResult" function="$function.SomeLib_v1.SomeMethod(1238, FF)" />
    </QUERY>
</REQUEST>

<RESPONSE>
    <RESULT>
        <INFO>
            <EVALRESULT>
                <MyFirstFunctionResult>1337</MyFirstFunctionResult>
            </EVALRESULT>
        </INFO>
    </RESULT>
</RESPONSE>

Funktionsbibliotek i APIet

PMS_v1
APIet erbjuder funktionsbiblioteket PMS_v1 där följande metoder är implementerade:

$function.PMS_v1.CalcContinousLengthFromCoordinate(<County>, <RoadMainNumner>, <RoadSubNumber>, <Direction.Code>, <Easting>, <Northing>)

$function.PMS_v1.CalcContinousLengthsFromCoordinates(<County>, <RoadMainNumner>, <RoadSubNumber>, <Direction.Code>, [{<Easting>, <Northing>}, {<Easting>, <Northing>}, {<Easting>, <Northing>} ...])

$function.PMS_v1.CalcCoordinateFromContinousLength(<County>, <RoadMainNumner>, <RoadSubNumber>, <Direction.Code>, <ContinousLength>)

$function.PMS_v1.CalcCoordinatesFromContinousLengths(<County>, <RoadMainNumner>, <RoadSubNumber>, <Direction.Code>, [<ContinousLength>, <ContinousLength>, <ContinousLength> ...])

Funktionsbiblioteket PMS_v1 kan endast exekveras på datatyperna:

• MeasurementData20
• MeasurementData100
• PavementData
• RoadData

TrainAnnouncement_v1

$function.TrainAnnouncement_v1.GetLocationsForTrain(<AdvertisedTrainIdent>, <ScheduledDepartureDateTime>)

Exempelanvändning

<REQUEST>
    <LOGIN authenticationkey="YourAPIKey"/>
    <QUERY runtime="true" objecttype="TrainStation" schemaversion="1">
        <FILTER>
            <IN name="LocationSignature" value="$function.TrainAnnouncement_v1.GetLocationsForTrain(91,2019-10-31)" />
        </FILTER>
    </QUERY>
</REQUEST>
        

Funktionsbiblioteket TrainAnnouncement_v1 kan endast exekveras på datatyperna:

• TrainAnnouncement
• TrainStation
• TrainMessage

Geometry_v1

$function.Geometry_v1.GetBuffer('<WKT>', <Distance>)

$function.Geometry_v1.GetBuffer(<GeometryType>,[<CoordinatePair>], <Distance>)

Exempelanvändning

<REQUEST>
    <LOGIN authenticationkey="YourAPIKey"/>
    <QUERY runtime="true" objecttype="TrainStation" schemaversion="1">
        <EVAL alias="Buffer" function="$function.Geometry_v1.GetBuffer('LINESTRING(10 10, 20 20)', 7)" />
    </QUERY>
</REQUEST>
        

<REQUEST>
    <LOGIN authenticationkey="YourAPIKey"/>
    <QUERY runtime="true" objecttype="TrainStation" schemaversion="1">
        <EVAL alias="Buffer" function="$function.Geometry_v1.GetBuffer(linestring,[10 10, 20 20], 7)" />
    </QUERY>
</REQUEST>
        

Funktionsbiblioteket Geometry_v1 kan exekveras på samtliga datatyper.

Geo-sökningar

Geo-fält är definerade som WKT, t.ex.: <SWEREF99TM>POINT(674707 6579684)</SWEREF99TM>. De fält som det är möjligt att ställa geo-frågor mot är i datamodellen markerade med . För tillfället finns stöd för följande geo-operatorer.

Within

<REQUEST>
    <LOGIN authenticationkey="SomeAuthenticationKey" />
    <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <FILTER>
     <WITHIN name="Geometry.SWEREF99TM" shape="box" value="276192 6576098, 280967 6579969"/>
    </FILTER>
  </QUERY>
</REQUEST>

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <FILTER>
      <WITHIN name="Geometry.SWEREF99TM" shape="polygon"
        value="343221.595823 6473809.616383,343065.083445 6473844.341895,
               343285.880000 6473971.780000,343221.595823 6473809.616383" />
    </FILTER>
  </QUERY>
</REQUEST>

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <FILTER>
      <WITHIN name="Geometry.SWEREF99TM" shape="center"
                value="343207 6473960" radius="100" />
    </FILTER>
  </QUERY>
</REQUEST>

Match	Miss

Intersects

Match	Miss

Near

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion">
    <FILTER>
        <NEAR name="Geometry.SWEREF99TM" value="353855 6423240" mindistance="1" maxdistance="20" />
    </FILTER>
  </QUERY>
</REQUEST>

Förändrat data

Från och med version 2 (changeid)

Följande fråga returnerar alla dataposter av typen SomeObjectType som uppdaterats eller raderats efter 2018-06-01T00:00:00.00.

Fråga:

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion" includedeletedobjects="true"
    changeid="0">
  <FILTER>
    <AND>
      <GT name="VersionField" value="2018-06-01T00:00:00.00" />
      <EQ name="DataField" value="SomeData" />
    </AND>
  </FILTER>
  </QUERY>
</REQUEST>

Svar:

<RESPONSE>
  <RESULT>
    <SomeObjectType>
      <Id>123</Id>
      <DataField>SomeData</DataField>
      <VersionField>2018-06-01T00:01:12.256</VersionField>
    </SomeObjectType>
    <SomeObjectType>
      <Id>456</Id>
      <DataField>SomeData</DataField>
      <VersionField>2018-06-01T00:02:21.196Z</VersionField>
      <Deleted>true</Deleted>
    </SomeObjectType>
    <INFO>
       <LASTCHANGEID>6678036140773081527</LASTCHANGEID>
    </INFO>
  </RESULT>
</RESPONSE>

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion" includedeletedobjects="true"
    changeid="6678036140773081527">
    <FILTER>
      <EQ name="DataField" value="SomeData" />
    </FILTER>
  </QUERY>
</REQUEST>

Före version 2 (lastmodified)

Följande fråga returnerar alla dataposter av typen SomeObjectType som uppdaterats eller raderats efter 2014-01-03T09:00:00.00Z.

Fråga:

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion" includedeletedobjects="true"
          lastmodified="true">
  <FILTER>
    <GT name="ModifiedTime" value="2014-01-03T09:00:00.00Z" />
  </FILTER>
  </QUERY>
</REQUEST>

Svar:

<RESPONSE>
  <RESULT>
    <SomeObjectType>
      <Id>123</Id>
      <DataField>The data</DataField>
      <ModifiedTime>2014-01-03T09:21:27.16Z</ModifiedTime>
    </SomeObjectType>
    <SomeObjectType>
      <Id>456</Id>
      <DataField>The other data</DataField>
      <ModifiedTime>2014-01-22T09:57:56.07Z</ModifiedTime>
      <Deleted>true</Deleted>
    </SomeObjectType>
    <INFO>
      <LASTMODIFIED datetime="2014-01-22T09:57:56.07Z"></LASTMODIFIED>
    </INFO>
  </RESULT>
</RESPONSE>

<REQUEST>
  <LOGIN authenticationkey="SomeAuthenticationKey" />
  <QUERY objecttype="SomeObjectType" schemaversion="SomeSchemaVersion" includedeletedobjects="true"
    lastmodified="true">
    <FILTER>
      <GT name="ModifiedTime" value="2014-01-22T09:57:56.07Z" />
    </FILTER>
  </QUERY>
</REQUEST>

Content-Type

Från och med version 2 måste POST-anropet ha någon av följande värde i Content-Type headern:

• application/xml
• text/xml
• text/plain (triggar ingen CORS preflight, mer info finns här.)

CORS

Normalt sett så får en webbläsare av säkerhetsskäl inte göra ett XMLHttpRequest till en annan domän (cross-domain) än den som sidan ursprungligen laddades ifrån. Cross-origin resource sharing (CORS) är en mekanism för att tillåta just detta. Trafikverkets öppna API för trafikinformation har stöd för CORS. Om användarens webbläsare har stöd för CORS kommer en Origin HTTP header att bifogas anropet och webbservicen kommer i svarets header att returnera Access-Control-Allow-Origin: *.

Läs mer om CORS – http://en.wikipedia.org/wiki/Cross-origin_resource_sharing