Getting Started

Overview#

The Unveiler API is a cloud based solution to verify the location of users. You can access the Unveiler API at https://api.unveiler.io.

The API is a GraphQL endpoint exposed over HTTP. The easiest way to get started is to make queries directly from the browser, so that's what we are going to do here.

API Key#

As a preliminary step we need to get an API key. Go to the Unveiler Dashboard, log in using your email and generate a new key. Copy the generated key and store it somewhere such that you can access it in the next step.

tip

You can refer in the description of the key that you are using it to experiment, such that you can later delete it when you're done experimenting.

My First Query#

Open up https://api.unveiler.io and you will see the "Playground", an interactive environment to help you explore the GraphQL schema, and build and run queries. It even comes with syntax highlighting!

Authorization#

First we need to set the API key created in the previous step. In the bottom-left there's a button "HTTP HEADERS" (to the right of "QUERY VARIABLES"), click on this button and fill the textfield which just opened up with:

{  "Authorization": "Bearer REPLACE_THIS_WITH_YOUR_API_KEY"}

This will add the Authorization HTTP header with your API key to all subsequent requests.

Query the API#

In the field above the "HTTP HEADER" field we can write our GraphQL query. Paste the query below into this field and press the run button in the middle of the screen.

query ValidPointClaimRequest {  verifyLocation(    tokenRequest: { claim: { point: { location: { latitude: 52.9519, longitude: -1.1841 }, radius: 100 } } }    context: {      gnssLog: "# \n# Header Description:\n# \n# Version: v2.0.0.1\n#\n# Raw,ElapsedRealtimeMillis,TimeNanos,LeapSecond,TimeUncertaintyNanos,FullBiasNanos,BiasNanos,BiasUncertaintyNanos,DriftNanosPerSecond,DriftUncertaintyNanosPerSecond,HardwareClockDiscontinuityCount,Svid,TimeOffsetNanos,State,ReceivedSvTimeNanos,ReceivedSvTimeUncertaintyNanos,Cn0DbHz,PseudorangeRateMetersPerSecond,PseudorangeRateUncertaintyMetersPerSecond,AccumulatedDeltaRangeState,AccumulatedDeltaRangeMeters,AccumulatedDeltaRangeUncertaintyMeters,CarrierFrequencyHz,CarrierCycles,CarrierPhase,CarrierPhaseUncertainty,MultipathIndicator,SnrInDb,ConstellationType,AgcDb,CarrierFrequencyHz\n#\nRaw,1495260698,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,1,0.0,16431,316129931564615,11,40.876319885253906,-85.53832074583623,0.0016427808441221714,17,-81583.78418521381,8.213904220610857E-4,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260698,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,3,0.0,16431,316129923668613,27,29.818252563476562,-489.8777472463323,0.6084177138004159,20,-355217.55933421943,3.4028234663852886E38,1.57542003E9,,,,1,,1,52.750877380371094,1.57542003E9\nRaw,1495260698,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,8,0.0,16431,316129927787640,17,35.78179168701172,645.4242601276492,0.0027843888383358717,17,426290.985523551,0.0013921944191679358,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,10,0.0,16431,316129919399692,12,42.306976318359375,803.2675912890118,0.0014686748618260026,17,549069.2010766398,7.343374309130013E-4,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,11,0.0,16431,316129932873693,28,29.3798770904541,29.020319194842855,0.629786748367239,20,-8105.547047361134,3.4028234663852886E38,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,14,0.0,16431,316129923430009,24,31.403287887573242,-177.94112884887727,0.004609512630850077,17,-126737.27151197789,0.0023047563154250383,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,17,0.0,16431,316129915263310,28,29.714963912963867,-496.6536200713599,0.005598495248705149,17,-345683.2528901036,0.0027992476243525743,1.57542003E9,,,,1,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,18,0.0,16431,316129933639553,17,35.86145782470703,237.04362229723483,0.0029263265896588564,17,138242.7709919729,0.0014631632948294282,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,22,0.0,16431,316129927719682,16,36.430076599121094,-263.27768270662636,0.0027408916503190994,17,-205144.4099664865,0.0013704458251595497,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,24,0.0,16392,316129915280620,1000000000,31.5046329498291,162.44566177289937,2.99792458E8,18,167.79776790934494,3.4028234663852886E38,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,27,0.0,16431,316129918120593,18,34.90118408203125,879.6037002496887,0.003268409753218293,17,545384.5828230947,0.0016342048766091466,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260699,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,28,0.0,16431,316129923538508,13,38.63100051879883,111.66776911559282,0.0021273831371217966,17,48254.940108973045,0.09621052796774333,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,32,0.0,16431,316129924839485,14,37.97731399536133,68.70944971204335,0.002293665194883942,17,16110.583133919241,0.0011468325974419713,1.57542003E9,,,,0,,1,52.750877380371094,1.57542003E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,1,0.0,16393,316129931564618,10,37.700767517089844,-85.54446856876893,0.003170882817357779,17,-98185.15786699297,0.0015854414086788893,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,3,0.0,16393,316129923668622,14,27.93844985961914,-490.29375771064974,0.6929503937546269,20,-392836.6688584145,3.4028234663852886E38,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,8,0.0,16393,316129927787619,8,35.587074279785156,645.442951474688,0.004044500179588795,17,493971.8852916871,0.0020222500897943974,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,10,0.0,16393,316129919399675,8,35.74829864501953,803.268433162477,0.003970120567828417,17,639354.0143587813,0.0019850602839142084,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,27,0.0,16393,316129918120538,9,44.06595230102539,879.6142772445455,0.0016062003560364246,17,798540.3949230267,8.031001780182123E-4,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,32,0.0,16393,316129924839478,20,27.673259735107422,68.65929105581381,0.009483734145760536,17,14439.915978635347,0.004741867072880268,1.17645005E9,,,,0,,1,7.513272285461426,1.17645005E9\nRaw,1495260700,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,6,0.0,16393,427266,233,25.07337760925293,-278.4052556618702,0.8235447814591392,22,-523.8324074909034,3.4028234663852886E38,1.59975002E9,,,,0,,3,61.51556396484375,1.59975002E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,22,0.0,32995,67711927237128,33,37.28288269042969,-486.7033490398899,0.0024459254927933216,17,-349228.7049792756,0.0012229627463966608,1.60031245E9,,,,0,,3,61.51556396484375,1.60031245E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,12,0.0,32995,67711922984932,69,27.061016082763672,650.7048978233943,0.007475753780454397,17,396446.70830520615,0.0037378768902271986,1.60143744E9,,,,0,,3,61.51556396484375,1.60143744E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,5,0.0,32995,67711931125945,33,37.781063079833984,607.4707726440392,0.002306343289092183,17,386813.4132974749,0.0011531716445460916,1.60256256E9,,,,0,,3,61.51556396484375,1.60256256E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,20,0.0,32995,67711926394741,59,29.16234016418457,785.9488544155611,0.005863156169652939,17,540411.6637978145,0.0029315780848264694,1.60312499E9,,,,1,,3,61.51556396484375,1.60312499E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,21,0.0,32995,67711935605049,33,36.32494354248047,144.40314516908256,0.002724412130191922,17,70473.52935890848,0.001362206065095961,1.60424998E9,,,,0,,3,61.51556396484375,1.60424998E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,105,0.0,32995,67711921724209,37,34.75782012939453,-690.4172884391737,0.0032619463745504618,17,-443858.0453540575,0.0016309731872752309,1.60481254E9,,,,0,,3,61.51556396484375,1.60481254E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,106,0.0,32995,67711918294500,33,36.61747741699219,976.1356441469397,0.0026323385536670685,17,670838.516463557,0.0013161692768335342,1.60537498E9,,,,0,,3,61.51556396484375,1.60537498E9\nRaw,1495260701,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,16,0.0,16431,316115867274795,14,29.24173927307129,291.8605181039311,0.005966212600469589,17,199813.57937009222,0.09900284945537303,1.56109798E9,,,,0,,5,61.96491241455078,1.56109798E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,27,0.0,16431,316115927847574,12,31.330848693847656,219.81329864129657,0.004690760280936956,17,133435.67932530362,0.09836512329560672,1.56109798E9,,,,0,,5,61.96491241455078,1.56109798E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,2,0.0,16392,316129903873849,1000000000,7.0,747.8069958021133,2.99792458E8,18,2.976863440608772,3.4028234663852886E38,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,4,0.0,19498,316129911418415,30,28.90699577331543,525.3660308271064,0.006144260987639427,17,293381.3506502631,0.0030721304938197136,1.57542003E9,,,,1,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,5,0.0,19498,316129911945535,12,39.76995086669922,-411.2340466129474,0.16095095607130594,20,-237991.85004471263,3.4028234663852886E38,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,9,0.0,19498,316129924798137,14,40.406097412109375,3.9459603366030938,0.0018279720097780228,17,-13718.844884194397,9.139860048890114E-4,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,15,0.0,16392,316129906102078,1000000000,12.436882019042969,-363.1356910819791,2.99792458E8,18,-1.093037011302429,3.4028234663852886E38,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,27,0.0,19498,316129909779601,31,28.176494598388672,125.88593735774339,0.006683358922600745,17,55235.723002584426,0.003341679461300373,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,30,0.0,19498,316129914691684,50,22.538860321044922,574.9920363330293,0.9355880614513667,20,319862.63586223207,3.4028234663852886E38,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260702,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,36,0.0,19498,316129921604038,16,36.64375305175781,356.4210190716258,0.0026742874179035425,17,198182.0146399804,0.0013371437089517713,1.57542003E9,,,,0,,6,52.750877380371094,1.57542003E9\nRaw,1495260703,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,4,0.0,18475,316129911418432,11,37.97267150878906,525.3839951150585,0.003073158673942089,17,304162.3454628842,0.0015365793369710445,1.17645005E9,,,,0,,6,7.513272285461426,1.17645005E9\nRaw,1495260703,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,5,0.0,18475,316129911945556,9,31.171018600463867,-410.44580273871543,0.0063400305807590485,17,-311726.05097740516,0.0031700152903795242,1.17645005E9,,,,0,,6,7.513272285461426,1.17645005E9\nRaw,1495260703,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,9,0.0,18475,316129924798141,13,30.823482513427734,3.9742362027955096,0.006598848383873701,17,-15679.415323069463,0.0032994241919368505,1.17645005E9,,,,0,,6,7.513272285461426,1.17645005E9\nRaw,1495260703,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,27,0.0,18475,316129909779523,8,31.680980682373047,125.89543544739718,0.005978514906018972,17,61967.15138053011,0.002989257453009486,1.17645005E9,,,,0,,6,7.513272285461426,1.17645005E9\nRaw,1495260703,696809000000,,,-1246808233190696589,0.0,4.857103093679639,,,0,30,0.0,18475,316129914691670,70,20.936952590942383,575.8079703421854,299.7951156747056,20,497079.50713497004,3.4028234663852886E38,1.17645005E9,,,,0,,6,7.513272285461426,1.17645005E9\n"    }  ) {    status    tokenResponse {      token {        iat        claim {          point {            location {              latitude              longitude            }            radius          }        }      }      jwt    }  }}

This is how your screen should like like after you entered the query and the HTTP Headers field:

Screenshot of Unveiler API Playground

Interpretting the Results#

After a couple of seconds your location verification request will be resolved and the results will be shown at the right half of your screen. These will look something like this:

{  "data": {    "verifyLocation": {      "status": "GRANTED",      "tokenResponse": {        "token": {          "iat": "1595846276",          "claim": {            "point": {              "location": {                "latitude": 52.9519,                "longitude": -1.1841              },              "radius": 100            }          }        },        "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGFpbSI6eyJwb2ludCI6eyJsb2NhdGlvbiI6eyJsYXRpdHVkZSI6NTIuOTUxOSwibG9uZ2l0dWRlIjotMS4xODQxfSwicmFkaXVzIjoxMDB9fSwicHJvb2YiOiJHTlNTIiwiaWF0IjoxNTk1ODQ2Mjc2fQ.Ko1otS6zZpZ1JpYymZpGXM22v7GQW0wqcU4cum_Yxb0xrbM2UGHCIwpKEvkOgA-ITEjj65AgLfs8AmNJJbUFMzVZmaATvVoy_wW2JMUn2oHcBstzc5wMUYrELjmGy0oOXJcdxX_EirKVkBaOW1FPf_m2iMZLxsLAhd9S2Afj8ICCnVULyuPCNxfsED-cqOdgzrIBzyHfq6jx9CclvK_Bo-uMML5_OymsvyLnFNCXplPbGx9pG2qjzBFp_K-zEnHlgRDxKUIkfn-9VxPYErQIFG7N4_lvJ_XN8XNiec6OW-WOkEpRaTiyfqzHYsoZy057c7D4gznr98Yl-NrFAVKT_Q"      }    }  }}

What has happened? When we made our request, we asked the Unveiler API to verify that our location was indeed within 100 meters of the coordinate with latitude and longitude of respectively 52.9519 and -1.1841. As context ("proof") we offered raw GNSS data.

The raw GNSS data was analysed and resolved to a location, which was verified to be within 100 meters of the coordinate we said we would be close to. Hence, the status of this request is GRANTED. (In fact, the GNSS measurements were taken at approximately 9.5 meters from the mentioned coordinate. Try requesting a claim with a smaller radius, such as 1 meter.)

Since our request was granted, we also receive a JWT, which contains these claims, cryptographically signed by Unveiler. This JWT can be used to proof to other parties the verified status of their location.