• Your shopping cart is empty!
Location Search by Latitude and Longitude

GeoDataSource™ Location Search Web Service

GeoDataSource™ Location Search Web Service is a REST API enable user to lookup for city name by using latitude and longitude coordinate. It will return the result in either JSON or XML containing the information of the nearest country, region, city, latitude, longitude, currency code, currency name, currency symbol, time of sunrise, time of sunset, time zone and distance of input coordinate with the city. The GeoDataSource™ Location Search Web Service consists of two APIs, Nearest City API and Nearest Cities API. Nearest City API will only return one result whereas the Nearest Cities API will return the list of cities within 20km. Paid plan of this Web Service will be auto-renewed and auto-recharged monthly. Below please find the syntax.

Product Name Price
Location Search Web Service (500 credits) FREE Add to cart
Location Search Web Service (10,000 credits) $50.00 USD/month Add to cart
Location Search Web Service (50,000 credits) $125.00 USD/month Add to cart
Location Search Web Service (250,000 credits) $300.00 USD/month Add to cart

GET https://api.geodatasource.com/v2/city

Features

  • No database to download, to install or to upgrade in the server side
  • Support HTTP or HTTPS queries up to 500 times per month

Request

Parameter Type Description
key string (required) API key.
lat double (required) Latitude of a location.
lng double (required) Longitude of a location.
format string (optional) Return the result in json (default) or xml format.
Valid values: json | xml

Response

Parameter Type Description
country string Two-character country code based on ISO 3166.
region string Region or state name.
city string City name.
latitude double Latitude of a location.
longitude double Longitude of a location.
currency_code string Currency code based on ISO 4217.
currency_name string Currency name.
currency_symbol string Currency symbol.
sunrise string Time of sunrise. (hh:mm format in local time, i.e, 07:47).
sunset string Time of sunset. (hh:mm format in local time, i.e 19:50).
time_zone string UTC time zone (with DST supported).
distance_km double Distance between the input coordinate and city coordinate in kilometers (km).

Example of response message

{
	"country":"US",
	"region":"California",
	"city":"Mountain View",
	"latitude":37.3861,
	"longitude":-122.084,
	"currency_code":"USD",
	"currency_name":"United States Dollar",
	"currency_symbol":"$",
	"sunrise":"06:45",
	"sunset":"19:35",
	"time_zone":"-08:00",
	"distance_km":0.0001
}

Location Search City API Sample Code
<?php
$apiKey = 'Enter_API_Key';
$params['format']   = 'json';
$params['lat']      = 37.3861;
$params['lng']      = -122.084;

$query = '';

foreach($params as $key=>$value){
	$query .= '&' . $key . '=' . rawurlencode($value);
}

////////////
//For https request, please make sure you have enabled php_openssl.dll extension.
//
//How to enable https
//- Uncomment ;extension=php_openssl.dll by removing the semicolon in your php.ini, and restart the apache.
//
//In case you have difficulty to modify the php.ini, you can always make the http request instead of https.
////////////
$result = file_get_contents('https://api.geodatasource.com/city?key=' . $apiKey . $query);

$data = json_decode($result);

print_r($data);
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;

public class GDS {
	public static void main(String[] args) {
		try {

		URL url = new URL("https://api.geodatasource.com/city?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084");
		HttpURLConnection conn = (HttpURLConnection) url.openConnection();
		conn.setRequestMethod("GET");
		conn.setRequestProperty("Accept", "application/json");

		if (conn.getResponseCode() != 200) {
			throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
		}

		BufferedReader br = new BufferedReader(new InputStreamReader(
			(conn.getInputStream())));

		String output;

		while ((output = br.readLine()) != null) {
			System.out.println(output);
		}

		conn.disconnect();

	  } catch (MalformedURLException e) {

		e.printStackTrace();

	  } catch (IOException e) {
		e.printStackTrace();
	  }
	}
}
Imports System.Net
Imports System.Security.Cryptography

Partial Public Class _Default
	Inherits System.Web.UI.Page

	Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
		Dim request As HttpWebRequest = Nothing
		Dim response As Net.HttpWebResponse = Nothing
		Dim stream As IO.Stream = Nothing

		Dim apiKey As String = "Enter_API_Key"
		Dim format As String = "json"
		Dim lat As Double = 37.3861
		Dim lng As Double = -122.084

		request = Net.WebRequest.Create("https://api.geodatasource.com/city?key=" & apiKey & _
		"&format=" & System.Web.HttpUtility.UrlEncode(format) & _
		"&lat=" & System.Web.HttpUtility.UrlEncode(lat) & _
		"&lng=" & System.Web.HttpUtility.UrlEncode(lng)

		request.Method = "GET"
		response = request.GetResponse()

		Dim reader As System.IO.StreamReader = New IO.StreamReader(response.GetResponseStream())

		Page.Response.Write(reader.ReadToEnd)
	End Sub
End Class
using Microsoft.VisualBasic;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Data;
using System.Diagnostics;
using System.Net;
using System.Security.Cryptography;

public partial class _Default : System.Web.UI.Page
{

	protected void Page_Load(object sender, System.EventArgs e)
	{
		HttpWebRequest request = null;
		System.Net.HttpWebResponse response = null;
		System.IO.Stream stream = null;

		string apiKey = "Enter_API_Key";
		string format = "json";
		double lat = 37.3861;
		double lng = -122.084;

		request = System.Net.WebRequest.Create("https://api.geodatasource.com/city?key=" + apiKey + "&format=" + System.Web.HttpUtility.UrlEncode(format) + "&lat=" + System.Web.HttpUtility.UrlEncode(lat) + "&lng=" + System.Web.HttpUtility.UrlEncode(lng));

		request.Method = "GET";
		response = request.GetResponse();

		System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream());

		Page.Response.Write(reader.ReadToEnd());
	}
}
import httplib
import urllib

p = { 'key': 'Enter_API_Key', 'format': 'json', 'lat': 37.3861, 'lng': -122.084 }

conn = httplib.HTTPConnection("api.geodatasource.com")
conn.request("GET", "/city?" + urllib.urlencode(p))
res = conn.getresponse()
print res.read()
$ curl https://api.geodatasource.com/city?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084
require 'uri'
require 'net/http'

uri = URI.parse("https://api.geodatasource.com/city?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)

response = http.request(request)
print response.body
Error Codes

error_code error_message
10000 Missing parameter.
10001 Invalid API key.
10002 API key disabled.
10003 API key expired.
10004 Insufficient credits.
10005 Unknown error.
10006 No record found.
10007 Invalid format value.
10008 Invalid latitude value.
10009 Invalid longitude value.

Example of error message

{
    "error": {
        "error_code": 10000,
        "error_message": "Missing parameter."
    }
}

GET https://api.geodatasource.com/v2/cities

Features

  • No database to download, to install or to upgrade in the server side
  • Support HTTP or HTTPS queries up to 500 times per month

Request

Parameter Type Description
key string (required) API key.
lat double (required) Latitude of a location.
lng double (required) Longitude of a location.
format string (optional) Return the result in json (default) or xml format.
Valid values: json | xml

Response

Parameter Type Description
country string Two-character country code based on ISO 3166.
region string Region or state name.
city string City name.
latitude double Latitude of a location.
longitude double Longitude of a location.
currency_code string Currency code based on ISO 4217.
currency_name string Currency name.
currency_symbol string Currency symbol.
sunrise string Time of sunrise. (hh:mm format in local time, i.e, 07:47).
sunset string Time of sunset. (hh:mm format in local time, i.e 19:50).
time_zone string UTC time zone (with DST supported).
distance_km double Distance between the input coordinate and city coordinate in kilometers (km).

Example of response message

[
	{
		"country":"US",
		"region":"California",
		"city":"Mountain View",
		"latitude":37.3861,
		"longitude":-122.084,
		"currency_code":"USD",
		"currency_name":"United States Dollar",
		"currency_symbol":"$",
		"sunrise":"06:21",
		"sunset":"19:51",
		"time_zone":"-08:00",
		"distance_km":0.0001
	},
	{
		"country":"US",
		"region":"California",
		"city":"Cuesta Park",
		"latitude":37.3775,
		"longitude":-122.082,
		"currency_code":"USD",
		"currency_name":"United States Dollar",
		"currency_symbol":"$",
		"sunrise":"06:21",
		"sunset":"19:51",
		"time_zone":"-08:00",
		"distance_km":0.9726
	},
	{
		"country":"US",
		"region":"California",
		"city":"Saint Francis Acres",
		"latitude":37.3883,
		"longitude":-122.095,
		"currency_code":"USD",
		"currency_name":"United States Dollar",
		"currency_symbol":"$",
		"sunrise":"06:21",
		"sunset":"19:51",
		"time_zone":"-08:00",
		"distance_km":1.0023
	}
]

Location Search Cities API Sample Code
<?php
$apiKey = 'Enter_API_Key';
$params['format']   = 'json';
$params['lat']      = 37.3861;
$params['lng']      = -122.084;

$query = '';

foreach($params as $key=>$value){
	$query .= '&' . $key . '=' . rawurlencode($value);
}

////////////
//For https request, please make sure you have enabled php_openssl.dll extension.
//
//How to enable https
//- Uncomment ;extension=php_openssl.dll by removing the semicolon in your php.ini, and restart the apache.
//
//In case you have difficulty to modify the php.ini, you can always make the http request instead of https.
////////////
$result = file_get_contents('https://api.geodatasource.com/cities?key=' . $apiKey . $query);

$data = json_decode($result);

print_r($data);
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;

public class GDS {
	public static void main(String[] args) {
		try {

		URL url = new URL("https://api.geodatasource.com/cities?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084");
		HttpURLConnection conn = (HttpURLConnection) url.openConnection();
		conn.setRequestMethod("GET");
		conn.setRequestProperty("Accept", "application/json");

		if (conn.getResponseCode() != 200) {
			throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
		}

		BufferedReader br = new BufferedReader(new InputStreamReader(
			(conn.getInputStream())));

		String output;

		while ((output = br.readLine()) != null) {
			System.out.println(output);
		}

		conn.disconnect();

	  } catch (MalformedURLException e) {

		e.printStackTrace();

	  } catch (IOException e) {
		e.printStackTrace();
	  }
	}
}
Imports System.Net
Imports System.Security.Cryptography

Partial Public Class _Default
	Inherits System.Web.UI.Page

	Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
		Dim request As HttpWebRequest = Nothing
		Dim response As Net.HttpWebResponse = Nothing
		Dim stream As IO.Stream = Nothing

		Dim apiKey As String = "Enter_API_Key"
		Dim format As String = "json"
		Dim lat As Double = 37.3861
		Dim lng As Double = -122.084

		request = Net.WebRequest.Create("https://api.geodatasource.com/cities?key=" & apiKey & _
		"&format=" & System.Web.HttpUtility.UrlEncode(format) & _
		"&lat=" & System.Web.HttpUtility.UrlEncode(lat) & _
		"&lng=" & System.Web.HttpUtility.UrlEncode(lng)

		request.Method = "GET"
		response = request.GetResponse()

		Dim reader As System.IO.StreamReader = New IO.StreamReader(response.GetResponseStream())

		Page.Response.Write(reader.ReadToEnd)
	End Sub
End Class
using Microsoft.VisualBasic;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Data;
using System.Diagnostics;
using System.Net;
using System.Security.Cryptography;

public partial class _Default : System.Web.UI.Page
{

	protected void Page_Load(object sender, System.EventArgs e)
	{
		HttpWebRequest request = null;
		System.Net.HttpWebResponse response = null;
		System.IO.Stream stream = null;

		string apiKey = "Enter_API_Key";
		string format = "json";
		double lat = 37.3861;
		double lng = -122.084;

		request = System.Net.WebRequest.Create("https://api.geodatasource.com/cities?key=" + apiKey + "&format=" + System.Web.HttpUtility.UrlEncode(format) + "&lat=" + System.Web.HttpUtility.UrlEncode(lat) + "&lng=" + System.Web.HttpUtility.UrlEncode(lng));

		request.Method = "GET";
		response = request.GetResponse();

		System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream());

		Page.Response.Write(reader.ReadToEnd());
	}
}
import httplib
import urllib

p = { 'key': 'Enter_API_Key', 'format': 'json', 'lat': 37.3861, 'lng': -122.084 }

conn = httplib.HTTPConnection("api.geodatasource.com")
conn.request("GET", "/cities?" + urllib.urlencode(p))
res = conn.getresponse()
print res.read()
$ curl https://api.geodatasource.com/cities?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084
require 'uri'
require 'net/http'

uri = URI.parse("https://api.geodatasource.com/cities?key=Enter_API_Key&format=json&lat=37.3861&lng=-122.084")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)

response = http.request(request)
print response.body
Error Codes

error_code error_message
10000 Missing parameter.
10001 Invalid API key.
10002 API key disabled.
10003 API key expired.
10004 Insufficient credits.
10005 Unknown error.
10006 No record found.
10007 Invalid format value.
10008 Invalid latitude value.
10009 Invalid longitude value.

Example of error message

{
    "error": {
        "error_code": 10000,
        "error_message": "Missing parameter."
    }
}