yardcodeng
v1.0.11
Published
A JS client for the YardCode.ng API.
Readme
yardcode-pkg v1.0.0
YardCodeNG JS Library
A lightweight and easy-to-use JavaScript client for the YardCode.ng API. This library enables you to seamlessly convert between geographic coordinates (latitude/longitude) and YardCodes in your JavaScript or TypeScript projects.
Features
- Convert a YardCode to geographic coordinates.
- Convert geographic coordinates to a YardCode.
- Automatically get the user's current browser coordinates and convert them to a YardCode.
- Simple, promise-based API.
- Fully typed for TypeScript projects.
Installation
You can integrate yardcodeng into your project in two ways, depending on your setup.
1. For Modern Projects (React, Vue, Node.js, etc.)
If you are using a package manager like npm, yarn, or pnpm, you can add yardcodeng to your project directly.
Install using npm:
npm install yardcodengInstall using yarn:
yarn add yardcodengInstall using pnpm:
pnpm add yardcodeng2. For Plain HTML, CSS & JS Projects (CDN)
If you are not using a build system, you can include the library directly in your HTML file via a CDN link. This will expose a global YardCode class.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>YardCodeNG Demo</title>
</head>
<body>
<h1>YardCodeNG Demo</h1>
<button id="find-me-btn">Find My YardCode</button>
<div id="result"></div>
<script src="https://cdn.jsdelivr.net/npm/yardcodeng@latest/dist/yardcodeng.umd.js"></script>
<script>
// The library is now available on the global `window.YardCode` object
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const yardCodeClient = new YardCode(apiKey);
const resultDiv = document.getElementById('result');
const findMeBtn = document.getElementById('find-me-btn');
findMeBtn.addEventListener('click', async () => {
try {
resultDiv.textContent = 'Finding your location...';
const response = await yardCodeClient.myCoordinateToYardCode();
if (response.status === 'success') {
resultDiv.textContent = `Your YardCode is: ${response.data.yard_code}`;
} else {
resultDiv.textContent = `Error: ${response.message}`;
}
console.log(response);
} catch (error) {
resultDiv.textContent = `Failed to get location: ${error.message}`;
console.error("An unexpected error occurred:", error);
}
});
</script>
</body>
</html>Uninstallation
To remove the package from your project:
Uninstall using npm:
npm uninstall yardcodengUninstall using yarn:
yarn remove yardcodengUninstall using pnpm:
pnpm remove yardcodengGetting Started
First, you need to get an API key from the YardCode.ng website.
Once you have your key, import and initialize the client.
In a TypeScript/ESM project:
import YardCode from 'yardcodeng';
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const yardCodeClient = new YardCode(apiKey);In a CommonJS (Node.js) project:
const YardCode = require('yardcodeng');
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const yardCodeClient = new YardCode(apiKey);In a plain HTML file (using the CDN):
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const yardCodeClient = new YardCode(apiKey);API Usage & Examples
All methods are asynchronous and return a Promise. It is recommended to use async/await for cleaner code.
1. yardCodeToCoordinate(yardCode)
Converts a YardCode string into geographic coordinates and other location data.
Parameters:
yardCode(string, required): The YardCode to convert (e.g.,"GR10 A20 (quzo)").
Example:
async function getCoordinatesFromYardCode() {
try {
const response = await yardCodeClient.yardCodeToCoordinate("GR10 A20 (quzo)");
console.log(response);
} catch (error) {
console.error("An unexpected error occurred:", error);
}
}
getCoordinatesFromYardCode();Response Structure
{
"status": "success",
"data": {
"calls_left": 990,
"easting": 600012.0275603182,
"latitude": 7.3782,
"longitude": 3.9062,
"northern": 1,
"northing": 815659.47838768,
"state": "Oyo State",
"status": "Successful",
"yard_code": "GR10A20(quzo)",
"zone_number": 31
},
}{
"status": "error",
"message": "YardCode is missing"
}or
{
"status": "error",
"message": "API request failed"
}2. coordinateToYardCode(coords)
Converts a pair of latitude and longitude coordinates into a YardCode.
Parameters:
coords(object, required): An object containing the latitude and longitude.lat(number, required): The latitude.lng(number, required): The longitude.
Example:
async function getYardCodeFromCoordinates() {
try {
const coordinates = { lat: 7.3782, lng: 3.9062 };
const response = await yardCodeClient.coordinateToYardCode(coordinates);
console.log(response);
} catch (error) {
console.error("An unexpected error occurred:", error);
}
}
getYardCodeFromCoordinates();Response Structure
The response structure is identical to yardCodeToCoordinate.
{
"status": "success",
"data": {
"calls_left": 990,
"easting": 600012.0275603182,
"latitude": 7.3782,
"longitude": 3.9062,
"northern": 1,
"northing": 815659.47838768,
"state": "Oyo State",
"status": "Successful",
"yard_code": "GR10A20(quzo)",
"zone_number": 31
},
}{
"status": "error",
"message": "Latitude and longitude are required"
}3. myCoordinateToYardCode()
Automatically retrieves the user's current coordinates using the browser's Geolocation API and converts them to a YardCode.
Important: This method will trigger a permission prompt in the user's browser, asking them to share their location. It will only work in a secure context (HTTPS).
Parameters:
- None.
Example:
async function getMyYardCode() {
try {
console.log("Requesting location...");
const response = await yardCodeClient.myCoordinateToYardCode();
console.log(response);
} catch (error) {
console.error("An unexpected error occurred:", error);
}
}
// It's best to call this function in response to a user action, like a button click.
document.getElementById('find-me-btn').addEventListener('click', getMyYardCode);Response Structure
The successful response structure is identical to the other methods.
{
"status": "success",
"data": {
"calls_left": 990,
"easting": 600012.0275603182,
"latitude": 7.3782,
"longitude": 3.9062,
"northern": 1,
"northing": 815659.47838768,
"state": "Oyo State",
"status": "Successful",
"yard_code": "GR10A20(quzo)",
"zone_number": 31
},
}If the user denies the location permission or the browser fails to get coordinates:
{
"status": "error",
"message": "Error getting coordinate"
}