bng2latlong Getting Started: Account, Keys & First Request

Getting started overview

Integrating with the bng2latlong API involves a sequence of steps designed to enable access to its UK-centric geocoding and reverse geocoding services. The process begins with account registration, followed by API key generation, and culminates in executing an initial API call. This guide focuses on efficiently completing these foundational steps to establish a working integration.

The bng2latlong service provides specific endpoints for converting British National Grid (BNG) coordinates to latitude/longitude, postcodes to coordinates, and vice versa, as detailed in the bng2latlong API documentation. It is designed for applications requiring precise geographical data within the United Kingdom.

Here is a quick reference table outlining the essential steps:

Create an account and get keys

To begin using bng2latlong, you must first create an account. The platform offers a free tier that supports up to 500 requests per day, which is suitable for initial testing and development. Paid plans are also available for higher request volumes, starting at £20/month for 1,000,000 requests/month, as outlined on the bng2latlong pricing page.

1. Navigate to the Signup Page: Visit the bng2latlong website and select a plan to initiate the registration process. This will typically involve providing an email address and setting a password.
2. Complete Registration: Follow the on-screen prompts to complete your account setup. This may include verifying your email address.
3. Access Dashboard: Once registered and logged in, you will be directed to your account dashboard.
4. Locate API Key: Within your dashboard, there will be a section dedicated to API keys or credentials. The exact location may vary, but it is typically found under headings like "API Settings," "Developer," or "Keys."
5. Generate (if necessary) and Copy Key: If an API key is not automatically provided, you may need to generate one. Once displayed, copy your unique API key. This key is essential for authenticating your API requests. Treat your API key as sensitive information to prevent unauthorized access to your account and usage limits.

Your first request

After obtaining your API key, you can make your first request. This example uses the Postcode to Latitude/Longitude API, converting a UK postcode to its corresponding geographic coordinates.

The bng2latlong API uses a RESTful architecture, accepting HTTP GET requests and returning JSON formatted responses. Authentication is typically handled via a query parameter or HTTP header, carrying your API key.

API Endpoint

For converting a postcode to coordinates, the primary endpoint resembles:

https://www.bng2latlong.co.uk/api/postcode/{postcode}?api_key={your_api_key}

Replace {postcode} with the actual UK postcode and {your_api_key} with the key obtained from your dashboard.

Example Request (cURL)

cURL is a command-line tool for making network requests and is often used for quick API testing. For example, to convert the postcode "SW1A 0AA" (Buckingham Palace, London):

curl -X GET "https://www.bng2latlong.co.uk/api/postcode/SW1A%200AA?api_key=YOUR_API_KEY"

Remember to replace YOUR_API_KEY with your actual API key.

Example Request (JavaScript)

When integrating into a web application or Node.js environment, the Fetch API (for browsers) or a library like axios (for Node.js) can be used. bng2latlong also provides a JavaScript SDK.

fetch('https://www.bng2latlong.co.uk/api/postcode/SW1A%200AA?api_key=YOUR_API_KEY')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Replace YOUR_API_KEY with your API key.

Expected Successful Response

A successful request will return a JSON object similar to this, providing the latitude and longitude:

{
  "status": 200,
  "postcode": "SW1A 0AA",
  "latitude": 51.501,
  "longitude": -0.141,
  "bng_easting": 529168,
  "bng_northing": 179549
}

The status field indicates the success or failure of the request (200 for success). The latitude and longitude fields provide the WGS84 coordinates, while bng_easting and bng_northing provide the British National Grid coordinates.

Common next steps

After successfully making your first API call, you might consider the following steps:

• Explore Other Endpoints: The bng2latlong API offers various endpoints, including BNG to Latitude/Longitude conversion, Latitude/Longitude to Postcode, and broader Geocoding/Reverse Geocoding services. Consult the bng2latlong API reference for a complete list and detailed parameters.
• Implement Error Handling: Integrate robust error handling into your application to manage cases such as invalid API keys, malformed requests, or rate limit exceedances. The API typically returns HTTP status codes and error messages within the JSON response to aid in debugging.
• Integrate into Your Application: Incorporate the API calls into your application's logic. This might involve dynamically fetching coordinates based on user input or enriching existing datasets with geographic information.
• Monitor Usage: Regularly check your API usage against your plan limits via your bng2latlong account dashboard to avoid interruptions in service.
• Review Security Practices: Ensure your API key is stored and transmitted securely. For client-side applications, consider using a backend proxy to protect your API key from being exposed publicly. The OAuth 2.0 Bearer Token Usage specification provides general guidelines for token security, which can be adapted for API keys.

Troubleshooting the first call

If your first API call does not return the expected results, consider these common troubleshooting steps:

• Check API Key: Verify that your API key is correctly copied and included in the request. Even minor typos can lead to authentication failures.
• Review Endpoint URL: Confirm that the API endpoint URL is accurate and matches the one specified in the bng2latlong documentation. Pay attention to case sensitivity and path parameters.
• Inspect Request Parameters: Ensure all required parameters (e.g., postcode) are correctly formatted and URL-encoded if necessary (e.g., spaces in postcodes should be %20).
• Examine HTTP Status Codes: The HTTP status code returned by the API provides immediate feedback on the request's outcome.
• 200 OK: The request was successful.
• 400 Bad Request: The request was malformed, or a required parameter was missing.
• 401 Unauthorized: The API key is missing or invalid.
• 403 Forbidden: The API key is valid, but you don't have permission to access the resource, or your daily limit has been exceeded.
• 404 Not Found: The requested resource (e.g., postcode) could not be found.
• Check Rate Limits: If you are making numerous requests, you might have hit your API rate limit. The free tier allows 500 requests per day. Check your account dashboard for current usage.
• Consult Documentation: The bng2latlong API documentation contains specific error codes and messages that can help diagnose issues.
• Contact Support: If you've exhausted all troubleshooting options, contact bng2latlong support for assistance.