SocketTools provides an API and components for obtaining the physical location of a computer system based on its external IP address. This can enable developers to know where their application is being used, and provide functionality such as automatically completing information based on the location of the user.
The connection to our location service is always secure and does not require you subscribe to any third-party services. The accuracy of this information can vary depending on the location, with the most detailed information being available for North America.
The data that maps the IP address to a location is sourced from several different databases. The country and time zone information for all locations is generally accurate. However, specific details such as city names, postal codes and specific geographic locations (e.g.: longitude and latitude) may have reduced accuracy, depending on the location.
The location service makes the following information available to your applications:
| Field | Description |
|---|---|
| AutonomousSystemNumber | An integer which is used to uniquely identify a global network (autonomous system) which is connected to the Internet. This value can be used to determine the ownership of a particular network. |
| CityName | A string which identifies the city at this location. These names will always be in English, regardless of the current system locale. If the city name cannot be determined, this value may contain an empty string. |
| Coordinates | A string which specifies the location expressed using the Universal Transverse Mercator (UTM) coordinate system with the WGS-84 ellipsoid. These coordinates are commonly used with the Global Positioning System (GPS). |
| CountryAlpha2 | A string which contains the ISO 3166-1 alpha-2 code assigned to the country. For example, the alpha-2 code for the United States is "US". |
| CountryAlpha3 | A string which contains the ISO 3166-1 alpha-3 code assigned to the country. For example, the alpha-3 code for the United States is "USA". |
| CountryCode | An integer value which identifies the country using the standard UN country code. For example, the numeric country code for the United States is 840. |
| CountryName | A string which contains the full name of the country in which the external IP address is located, such as "United States". These names will always be in English, regardless of the current system locale. |
| IPAddress | A string which contains the external IP address for the local system. If the system has been assigned multiple IP addresses, it reflects the address of the interface used to establish the connection with the location server. |
| Latitude | A real number which specifies the latitude of the location in decimal format. A positive value indicates a location which is north of the equator, while a negative value is a location which is south of the equator. |
| LocalTime | Information about the current date and time at the location, adjusted for its time zone and whether or not it's in daylight savings time. |
| LocationId | A string which contains contains a string of hexadecimal characters which uniquely identifies the location for this computer system. This value is used internally by the location service, and may also be used by the application for its own purposes. |
| Longitude | A real number which specifies the longitude of the location in decimal format. A positive value indicates a location which is east of the prime meridian, while a negative value is a location which is west of the prime meridian. |
| Organization | A string which identifies the organization associated with the local system's external IP address. For residential end-users this is typically the name of their Internet Service provider, however it may also identify a private company. |
| PostalCode | A string which contains the postal code associated with the location. In the United States, this is a 5-digit numeric code. Local delivery portions of a postal code (such as the ZIP+4 code in the United States) are not included. |
| RegionCode | An integer which identifies the geographical region. This value corresponds to standard UN M49 region codes. |
| RegionName | A string which identifies a broad geographical area, such as "North America" or "Southeast Asia". |
| Subdivision | A string which identifies a geopolitical subdivision within a country. In the United States, this will contain the full name of the state or commonwealth. In Canada, this will contain the name of the province or territory. |
| SubdivisionCode | A string which is either a two- or three-letter code which identifies a geopolitical subdivision within the country. These codes are defined by the ISO 3166-2 standard. For example, the code for the state of California in the United States is "CA". |
| Timezone | A string which specifies the full time zone name. These names are defined by the Internet Assigned Numbers Authority (IANA) and have values like "America/Los_Angeles" and "Europe/London". |
| TimezoneOffset | A integer which specifies the number of seconds east or west of the prime meridian (UTC). A positive value indicates a time zone which is east of the prime meridian and a negative value indicates a time zone which is west of the prime meridian. |
| TzShortName | A string which specifies the abbreviated time zone code. If daylight savings time is used within the time zone, then this value can change based on whether or not daylight savings is in effect. If a short time zone code cannot be determined, a value such as "UTC+9" may be returned, indicating the number of hours ahead or behind UTC. |
It is important to keep in mind that software which is designed to protect the privacy of users, such as those which route all Internet traffic through proxy servers or VPNs, can significantly impact the accuracy of this information. In this case, the data returned in this structure may reflect the location of the network or proxy server, and not the location of the person using your application.
It is recommended you always request permission from the user before acquiring their location, have them confirm the location is correct and provide a mechanism for them to update the information.
Getting Started
To get started with the SocketTools location service, download an evaluation copy of SocketTools 10. The service is accessed using the Web Services API when using the Library Edition. The .NET Edition and ActiveX Edition include the WebLocation components which make it easy to query the service and return location information for the local system. You can review the technical documentation here:
SocketTools WebLocation .NET Class
SocketTools WebLocation ActiveX Control
Examples are included with SocketTools which demonstrates how to use the location service, and if you have any questions on how to use the service, we provide free technical support.