w3w node wrapper

What3words Wrapper JavaScript API

مكتبة JavaScript لتقديم طلبات إلى What3Words REST API. الآن مع دعم أفضل للاستخدام داخل كل من المتصفح والبيئات القائمة على العقدة! راجع وثائق What3Words Public API لمزيد من المعلومات حول كيفية استخدام API REST.

جدول المحتويات

• ملخص
• ثَبَّتَ
• الاستخدام
  • جافا سكريبت
  • TypeScript
• الوثائق
  • What3WordsService
  • العملاء
  • ينقل
  • أمثلة
    • الفانيليا Autosuggest
    • خريطة الفانيليا
• أمثلة
  • CustomTransport
  • Autosuggest
  • تحويل إلى إحداثيات
  • تحويل إلى عنوان ثلاث كلمة
  • اللغات المتاحة
  • قسم الشبكة

ملخص

يمنحك What3Words JavaScript Wrapper إمكانية الوصول البرنامجي إلى:

• تحويل عنوان 3 كلمة إلى إحداثيات
• تحويل الإحداثيات إلى عنوان 3 كلمة
• الوظيفة الأكثر تلقائيًا التي تأخذ عنوان كلمة غير صحيحة بعض الشيء ، وتقترح قائمة بعناوين الكلمات 3 الصالحة
• الحصول على قسم من شبكة 3M × 3M What3words لمربع محيط.
• حدد لغات العنوان الدعم 3 Word حاليًا.

ثَبَّتَ

NPM:

npm install @what3words/api

غزل:

yarn add @what3words/api

إذا كنت ترغب في استخدام وسائل النقل المدمجة ، فستحتاج أيضًا إلى تثبيت تبعيات الأقران لهم. لمزيد من المعلومات حول عمليات النقل الافتراضية ، اقرأ القسم الخاص بنقل النقل.

الاستخدام

جافا سكريبت

 const what3words ,
  { fetchTransport } = require ( '@what3words/api' ) ;

const apiKey = '<YOUR_API_KEY>' ;
const config = {
  host : 'https://api.what3words.com' ,
  apiVersion : 'v3' ,
} ;
const transport = fetchTransport ( ) ; // or you can import 'axiosTransport' instead
const w3wService = what3words ( apiKey , config , { transport } ) ;

// you can uncomment the following lines to set your api key and config after instantiation of the w3w service
// w3wService.setApiKey(apiKey);
// w3wService.setConfig(config);

TypeScript

 import what3words , {
  ApiVersion ,
  Transport ,
  What3wordsService ,
  axiosTransport ,
} from '@what3words/api' ;

const apiKey = '<YOUR_API_KEY>' ;
const config : {
  host : string ;
  apiVersion : ApiVersion ;
} = {
  host : 'https://api.what3words.com' ,
  apiVersion : ApiVersion . Version3 ,
} ;
const transport : Transport = axiosTransport ( ) ;
const w3wService : What3wordsService = what3words ( apiKey , config , { transport } ) ;

// code continues... 

الوثائق

خدمة What3Words

يوفر What3wordsService طريقة سريعة وسهلة لإنشاء إنشاء عملاء API الذين يمكن استخدامه لتقديم طلبات مقابل What3Words API. كما يوفر وظائف مساعد لإعداد تكوين واجهة برمجة التطبيقات ، مثل Post و API ومفتاح API الخاص بك عبر عملاء What3Words API.

العملاء

يتم استخدام عملاء What3Words API في هذه المكتبة للتحقق من صحة خيارات الطلب ، والسلسلة والتعامل مع الطلب/الاستجابة والأخطاء مقابل نقطة نهاية API. يمتد كل عميل فئة ApiClient المجردة.

هناك عميل محدد لكل طلب ويمكنك استخدامه بشكل مستقل عن What3wordsService . يمكن أن يكون هذا مفيدًا بشكل خاص إذا كنت ترغب في تمديد سلوك العميل ، وتقليل الكود الخاص بك ، أو في مثال أكثر تطرفًا ، استخدم نقلًا مخصصًا لمعالجة الطلبات بشكل مختلف في كل عميل.

يقبل كل عميل المعلمات التالية:

المعلمة	نوع البيانات	القيمة الافتراضية
apikey	خيط	''
تكوين	config.host	https://api.what3words.com
	config.apiversion	v3

ينقل

النقل هو وظيفة مسؤولة عن تنفيذ الطلب ضد API. بالنظر إلى ClientRequest يجب أن يعيد النقل وعدًا يحل إلى TransportResponse .

يتكون ClientRequest من الخصائص التالية:

ملكية	نوع البيانات
يستضيف *	string
url *	string
طريقة *	get أو post
استفسار	object
الرؤوس	object
جسم	object
شكل *	json أو geojson . الافتراضي: json

يتكون TransportResponse من الخصائص التالية:

ملكية	نوع البيانات
حالة *	number
Statustext *	string
جسم *	any
الرؤوس	object

هناك نوعان من وسائل النقل المدمجة مع هذه المكتبة التي يمكنك استخدامها ؛ إما التقاطع المتقاطع أو البديهية. من خلال تحديد النقل الذي ترغب في استخدامه عند تهيئة What3wordsService أو عميل ، إذا كنت ترغب في إنشاء إنشاء عميل لنفسك.

مدمجة

هناك نوعان من وسائل النقل المدمجة:

• المتقاطع
• البديهية

من أجل استخدام أي من هذين ، ستحتاج إلى تثبيت تبعية الأقران. بشكل افتراضي ، يتم افتراض الإحضار المتقاطع من خلال What3wordsService أو أي عميل تم تأسيسه حيث لا يتم توفير أي تجاوز.

NPM:

npm install cross-fetch

أو

npm install axios

غزل:

yarn add cross-fetch

أو

yarn add axios

مخصص

يمكنك توفير النقل المخصص الخاص بك ، إذا كنت ترغب في استخدام مكتبة أخرى لمعالجة الطلبات ، والتي قد تكون مفيدة إذا كان لديك تكاملات أخرى أو كنت تستخدم بالفعل مكتبة HTTP في مكان آخر.

من أجل القيام بذلك ، تحتاج إلى تحديد Transport الخاص بك ونقله إلى What3wordsService أو العميل لاستخدامه.

يجب أن يكون Transport المخصص الذي تنشئه وظيفة تقبل ClientRequest كوسيطة وإرجاع وعد يحل إلى TransportResponse .

أمثلة

النقل المخصص

 import what3words , { ClientRequest , TransportResponse } from '@what3words/api' ;
import superagent from 'superagent' ;

const API_KEY = '<YOUR_API_KEY>' ;
const config = { } ; // This will ensure we do not override the defaults

function customTransport < ResponseType > (
  request : ClientRequest
) : Promise < TransportResponse < ResponseType > > {
  const {
    method ,
    host ,
    url ,
    query = { } ,
    headers = { } ,
    body = { } ,
    format ,
  } = request ;
  return new Promise ( resolve =>
    superagent [ method ] ( ` ${ host } ${ url } ` )
      . query ( { ... query , format } )
      . send ( body || { } )
      . set ( headers )
      . end ( ( err , res ) => {
        if ( err || ! res )
          return resolve ( {
            status : err . status || 500 ,
            statusText : err . response . text || 'Internal Server Error' ,
            headers : err . headers || { } ,
            body : err . response . text || null ,
          } ) ;
        const response : TransportResponse < ResponseType > = {
          status : res . status ,
          statusText : res . text ,
          headers : res . headers ,
          body : res . body ,
        } ;
        resolve ( response ) ;
      } )
  ) ;
}

const service = what3words ( API_KEY , config , { transport : customTransport } ) ;
service
  . availableLanguages ( )
  . then ( ( { languages } ) => console . log ( 'Available languages' , languages ) ) ;

Autosuggest

 import {
  AutosuggestClient ,
  AutosuggestOptions ,
  AutosuggestResponse ,
} from '@what3words/api' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : AutosuggestClient = AutosuggestClient . init ( API_KEY ) ;
const options : AutosuggestOptions = {
  input : 'filled.count.s' ,
} ;
client
  . run ( options )
  . then ( ( res : AutosuggestResponse ) =>
    console . log ( `suggestions for " ${ options . input } "` , res )
  ) ;

تحويل إلى إحداثيات

 import {
  ConvertToCoordinatesClient ,
  ConvertToCoordinatesOptions ,
  FeatureCollectionResponse ,
  LocationGeoJsonResponse ,
  LocationJsonResponse ,
} from '@what3words/api' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : ConvertToCoordinatesClient =
  ConvertToCoordinatesClient . init ( API_KEY ) ;
const options : ConvertToCoordinatesOptions = { words : 'filled.count.soap' } ;

// If you want to retrieve the JSON response from our API
client
  . run ( { ... options , format : 'json' } ) // { format: 'json' } is the default response
  . then ( ( res : LocationJsonResponse ) =>
    console . log ( 'Convert to coordinates' , res )
  ) ;

// If you want to retrieve the GeoJsonResponse from our API
client
  . run ( { ... options , format : 'geojson' } )
  . then ( ( res : FeatureCollectionResponse < LocationGeoJsonResponse > ) =>
    console . log ( 'Convert to coordinates' , res )
  ) ;

تحويل إلى عنوان ثلاث كلمة

 import {
  ConvertTo3waClient ,
  ConvertTo3waOptions ,
  FeatureCollectionResponse ,
  LocationGeoJsonResponse ,
  LocationJsonResponse ,
} from '@what3words/api' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : ConvertTo3waClient = ConvertTo3waClient . init ( API_KEY ) ;
const options : ConvertTo3waOptions = {
  coordinates : { lat : 51.520847 , lng : - 0.195521 } ,
} ;

// If you want to retrieve the JSON response from our API
client
  . run ( { ... options , format : 'json' } ) // { format: 'json' } is the default response
  . then ( ( res : LocationJsonResponse ) => console . log ( 'Convert to 3wa' , res ) ) ;

// If you want to retrieve the GeoJsonResponse from our API
client
  . run ( { ... options , format : 'geojson' } )
  . then ( ( res : FeatureCollectionResponse < LocationGeoJsonResponse > ) =>
    console . log ( 'Convert to 3wa' , res )
  ) ;

اللغات المتاحة

 import {
  AvailableLanguagesClient ,
  AvailableLanguagesResponse ,
} from '@what3words/api' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : AvailableLanguagesClient = AvailableLanguagesClient . init ( API_KEY ) ;
client
  . run ( )
  . then ( ( res : AvailableLanguagesResponse ) =>
    console . log ( 'Available Languages' , res )
  ) ;

قسم الشبكة

 import {
  GridSectionClient ,
  GridSectionOptions ,
  FeatureCollectionResponse ,
  GridSectionGeoJsonResponse ,
  GridSectionJsonResponse ,
} from '../src' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : GridSectionClient = GridSectionClient . init ( API_KEY ) ;
const options : GridSectionOptions = {
  boundingBox : {
    southwest : { lat : 52.208867 , lng : 0.11754 } ,
    northeast : { lat : 52.207988 , lng : 0.116126 } ,
  } ,
} ;

// If you want to retrieve the JSON response from our API
client
  . run ( { ... options , format : 'json' } ) // { format: 'json' } is the default response
  . then ( ( res : GridSectionJsonResponse ) => console . log ( 'Grid Section' , res ) ) ;

// If you want to retrieve the JSON response from our API
client
  . run ( { ... options , format : 'geojson' } ) // { format: 'json' } is the default response
  . then ( ( res : FeatureCollectionResponse < GridSectionGeoJsonResponse > ) =>
    console . log ( 'Grid Section' , res )
  ) ;

يجب ألا يتجاوز المربع المطلوب 4 كم من الزاوية إلى الزاوية ، أو سيتم إرجاع خطأ BadBoundingBoxtOobig. يجب أن تكون الخطوط العرضية> = -90 و <= 90 ، ولكن يُسمح للطول بالالتفاف حوالي 180. لتحديد صندوق محيط يعبر معادتي-الطول ، يستخدم خط الطول أكبر من 180.

التحقق من صحة المدخلات

 import {
  GridSectionClient ,
  GridSectionOptions ,
  FeatureCollectionResponse ,
  GridSectionGeoJsonResponse ,
  GridSectionJsonResponse ,
} from '../src' ;

const API_KEY = '<YOUR_API_KEY>' ;
const client : GridSectionClient = GridSectionClient . init ( API_KEY ) ;
const options : GridSectionOptions = {
  boundingBox : {
    southwest : { lat : 52.208867 , lng : 0.11754 } ,
    northeast : { lat : 52.207988 , lng : 0.116126 } ,
  } ,
} ;

// Search a string for any character sequences that could be three word addresses
client . findPossible3wa ( 'filled.count.soap' ) ; // returns ['filled.count.soap']
client . findPossible3wa (
  'this string contains a three word address substring: filled.count.soap'
) ; // returns ['filled.count.soap']
client . findPossible3wa ( 'filled.count' ) ; // returns []

// Search a string for any character sequences that could be three word addresses
client . isPossible3wa ( 'filled.count.soap' ) ; // returns true
client . isPossible3wa (
  'this string contains a three word address substring: filled.count.soap'
) ; // returns false
client . isPossible3wa ( 'filled.count' ) ; // returns false

// Search a string for any character sequences that could be three word addresses
client . isValid3wa ( 'filled.count.soap' ) ; // returns Promise<true>
client . isValid3wa (
  'this string contains a three word address substring: filled.count.soap'
) ; // returns Promise<false>
client . isValid3wa ( 'filled.count.negative' ) ; // returns Promise<false>