Geuza na fungua anwani za Alkax Grid

Alkax Grid v1 huipa koordineti rejeleo fupi na thabiti la seli. Kila seli ina upana wa kawaida wa mita tano. Anwani ya Grid hutambua seli ya mahali; si eneo lililosajiliwa la Alkax, kitambulisho cha eneo, uthibitisho wa umiliki, au ushahidi kwamba eneo lipo hapo. Kufungua msimbo hufanya kazi pia kwa seli zisizo na wakazi.

Muundo sanifu ni CC-XXYY-LLLLL: nafasi ya majina ya nchi yenye herufi mbili, herufi nne za eneo na herufi tano za seli ya ndani. Msimbo hutumia alfabeti 23456789CFGHJMPQRVWX. V1 inajumuisha nafasi 55 za majina ya nchi za Afrika. Asili zake haziwezi kubadilishwa; mabadiliko ya data ya mipaka yanaweza kuathiri nchi ambayo koordineti iliyogeuzwa hupewa, lakini hayawezi kusogeza fremu iliyochapishwa ya v1. Mipaka ni data ya rejeleo ya ramani, si mipaka ya upimaji.

Katika programu ya Alkax

Maelezo ya eneo lililohifadhiwa hukuruhusu kunakili anwani ya Grid, na maandishi ya kushiriki pamoja na kurasa za umma za anwani iliyoshirikiwa huijumuisha inapopatikana. Utafutaji wa ramani hukubali anwani sanifu ya Grid na kukupeleka kwenye kitovu cha seli iliyofunguliwa. Matokeo hayo yanawakilisha mahali pa seli, si eneo lililosajiliwa; vichujio vya maeneo yaliyohifadhiwa havitumiki. Ramani hutumia endpoint maalumu ya first-party kufungua msimbo; endpoint hiyo haipo kwenye kichunguzi cha umma cha Developer API na haihitaji ufunguo wa msanidi.

Uthibitishaji na mgao

Operesheni zote mbili zinahitaji kitambulisho cha msanidi upande wa seva katika X-Alkax-Key chenye ruhusa ya places:read. Zinafanya kazi kwa vitambulisho vya Sandbox na Production. Hifadhi siri kwenye seva yako; usiiweke wazi kwenye msimbo wa kivinjari. Maombi huhesabiwa katika mgao wa kawaida wa kila mwezi wa Developer API na mipaka yake ya kasi; hakuna mgao tofauti wa Grid. Tazama mwongozo wa Developer Platform na mwongozo wa uthibitishaji. Kabla ya kutuma ombi, weka ALKAX_KEY iwe ufunguo wako wa Sandbox au Production:

export ALKAX_KEY="ak_test_<key-id>.<secret>"

Geuza viwianishi

Tuma latitudo na longitudo kama nambari za JSON. Latitudo lazima iwe kati ya -90 na 90, na longitudo kati ya -180 na 180:

curl "https://api.alkax.io/api/v1/addresses/grid/encode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"latitude":-1.2921,"longitude":36.8219}'

Nairobi ni vekta ya rejeleo iliyochapishwa. Jibu lake ni:

{
  "version": 1,
  "canonicalAddress": "KE-3R43-XMWRR",
  "countryCode": "KE",
  "centerLatitude": -1.2920930818547325,
  "centerLongitude": 36.82189788797723,
  "cellSizeMetres": 5
}

Kugeuza kwanza hutafuta nchi kwa kutumia jiometri ya mipaka ya nchi iliyosanidiwa, kisha hutumia fremu isiyobadilika ya nchi hiyo. Koordineti iliyo nje ya jiometri ya nchi inayotumika au fremu ya v1 inayolingana hurudisha 422. Jiometri ya mipaka isipoweza kupakiwa, kugeuza hurudisha 503.

Fungua anwani sanifu

Tuma anwani katika JSON. Simu hii hufungua vekta hiyo hiyo iliyochapishwa na kurudisha kitovu cha seli:

curl "https://api.alkax.io/api/v1/addresses/grid/decode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"address":"KE-3R43-XMWRR"}'

Kufungua hutumia sajili isiyobadilika ya fremu za v1 na hakupakii jiometri ya nchi wala kuangalia kama eneo lipo kwenye seli. Herufi ndogo na nafasi za pembeni zinakubaliwa na kusawazishwa katika canonicalAddress. Huduma hukubali mfuatano wa anwani wenye hadi herufi 32 kabla ya kuthibitisha muundo; matokeo sanifu huwa na herufi 13 kila wakati.

Anwani za Grid katika majibu ya maeneo

Koordineti inapokuwa ndani ya wigo wa v1, majibu ya msingi ya kusoma, kutafuta, kuunda na kusasisha maeneo huwa na kitu cha gridAddress katika kiwango cha juu. Thamani yake ni null koordineti isipoweza kuhusishwa na fremu inayotumika. Kwa mfano, jibu huwa na:

{
  "id": "<registered-place-uuid>",
  "plusCode": "<registered-place-plus-code>",
  "gridAddress": {
    "version": 1,
    "canonicalAddress": "KE-3R43-XMWRR",
    "countryCode": "KE",
    "centerLatitude": -1.2920930818547325,
    "centerLongitude": 36.82189788797723,
    "cellSizeMetres": 5
  }
}

Majibu mafupi ya GET /api/v1/addresses/{plusCode} na POST /api/v1/addresses/verify pia yana gridAddress inayoweza kuwa null katika kiwango cha juu. Jibu la pasipoti ya umma huiweka ndani ya geography.gridAddress. Misimbo hii ni vitambulisho tofauti: id hutambua eneo lililosajiliwa, plusCode hutambua Plus Code yake iliyopo, na gridAddress.canonicalAddress hutambua seli ya v1. Seli ya Grid haithibitishi kwamba eneo la Alkax limesajiliwa hapo.

Makosa na mipaka

Makosa ya huduma hutumia kitu cha kawaida cha jibu chenye code, message na orodha ya errors. Kila kipengele cha orodha hiyo kina sehemu za code, description na severity. Makosa ya uthibitishaji wa mwili wa ombi hurudisha orodha ya makosa ya uthibitishaji badala yake.

Hali	Inapotokea
400	Viwianishi visivyopo au vilivyo nje ya mipaka hurudisha orodha ya makosa ya uthibitishaji. Anwani tupu au yenye zaidi ya herufi 32 pia hukosa uthibitishaji wa ombi. Anwani iliyoharibika, nafasi ya majina isiyotumika au thamani ya msimbo isiyotumika hurudisha AddressGridInvalidRequest katika kitu cha kawaida cha kosa.
422	Koordineti ya kugeuza iko nje ya jiometri ya nchi inayotumika au fremu ya v1 (AddressGridOutsideCoverage)
503	Jiometri ya nchi haipatikani kwa kugeuza (AddressGridGeometryUnavailable)
401	Kitambulisho cha msanidi hakipo au si sahihi
403	Kitambulisho hakina ruhusa ya places:read
402	Usajili wa Production haufanyi kazi au hautoi ufikiaji wa Production
429	Mgao wa maombi wa mradi au usajili umeisha, au kikomo cha kasi kimefikiwa

Kwa mfano, jibu la nje ya wigo lina muundo huu:

{
  "code": "AddressGridOutsideCoverage",
  "message": "The coordinate is outside Alkax Grid v1 coverage.",
  "errors": [
    {
      "code": "AddressGridOutsideCoverage",
      "description": "The coordinate is outside Alkax Grid v1 coverage.",
      "severity": "Error"
    }
  ]
}

encode pekee hutegemea jiometri ya nchi. Operesheni ya decode inaweza kurudisha 400 kwa ingizo lisilo sahihi, lakini hairudishi 422 au 503 kwa sababu ya wigo wa jiometri. Mipaka ya nchi ni data ya rejeleo ya ramani, si mipaka ya upimaji; koordineti zilizo kwenye mipaka ya poligoni zinaweza kukosa nchi. Tazama rejeleo la API kwa miundo ya endpoint iliyochapishwa.