• API 功能
    • 提供精准、高效的地理坐标逆编码接口;
    • 返回的地址包含详细的位置信息;
    • 一次可返回坐标周边的 10 个地址信息;
    • 全接口支持 HTTPS(TLS v1.0 / v1.1 / v1.2 / v1.3);
    • 全面兼容 Apple ATS;
    • 全国多节点 CDN 部署;
    • 接口极速响应,多台服务器构建 API 接口负载均衡。
    • 接口调用状态与状态监控
  • API 文档

    接口地址: https://api.gugudata.com/location/geodecode

    返回格式: application/json; charset=utf-8

    请求方式: GET

    请求协议: HTTPS

    请求示例: https://api.gugudata.com/location/geodecode?appkey={{YOUR_APPKEY}}&longitude={{YOUR_VALUE}}&latitude={{YOUR_VALUE}}

    数据预览: https://www.gugudata.com/preview/geodecode

    接口测试: https://api.gugudata.com/location/geodecode/demo

    请求参数(GET 请求方式可参见下方示例代码)

    参数名 参数类型 是否必须 默认值 备注
    appkey string YOUR_APPKEY 付费后获取的 APPKEY
    longitude string YOUR_VALUE 经度值
    latitude string YOUR_VALUE 纬度值

    返回参数

    参数名 参数类型 备注
    DataStatus.StatusCode int 接口返回状态码
    DataStatus.StatusDescription string 接口返回状态说明
    DataStatus.ResponseDateTime string 接口数据返回时间
    DataStatus.DataTotalCount int 此条件下的总数据量,一般用于分页计算
    Data.Country string 国家
    Data.Province string
    Data.City string
    Data.District string
    Data.Township string 县/街道
    Data.Name string 位置名称
    Data.Address string 位置地址
  • 接口 HTTP 响应标准状态码
    状态码 状态码解释 备注
    200 接口正常响应 业务状态码参见下方 接口自定义状态码
    403 请求频率超限 CDN 层通过 IP 请求频率智能判断,一般的高频请求不会触发此状态码
  • 接口自定义状态码
    自定义状态码 自定义状态码解释 备注
    100 正常返回 可通过判断此状态码断言接口正常返回
    -1 请求失败 请求处理请求失败
    501 参数错误 请检查您传递的参数个数以及参数类型是否匹配
    502 请求频率受限 一般建议每秒请求不超过 5 次,我们不限制请求总次数,但当单位时间内请求次数过多或检测到恶意抓取数据、流量攻击等异常时,接口会拦截服务器错误并返回此状态码,请适当降低请求频率。
    503 APPKEY 权限超限/订单到期 请至开发者中心检查您的 APPKEY 是否到期或是否权限超限
    504 APPKEY 错误 请检查传递的 APPKEY 是否为开发者中心获取到的值
    505 请求的次数超出接口限制 请检查对应接口是否有请求次数限制以及您目前的接口请求剩余次数
    900 接口内部响应错误 接口可用性为 99.999%,如获取到此状态码请邮件联系我们
  • 代码请求示例
    curl --location --request GET 'https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE'
    CURL *curl;
    CURLcode res;
    curl = curl_easy_init();
    if(curl) {
      curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "GET");
      curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE");
      curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
      curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
      struct curl_slist *headers = NULL;
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      res = curl_easy_perform(curl);
    }
    curl_easy_cleanup(curl);
    var requestOptions = {
      method: 'GET',
      redirect: 'follow'
    };
    fetch("https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE", requestOptions)
      .then(response => response.text())
      .then(result => console.log(result))
      .catch(error => console.log('error', error));
    var client = new RestClient("https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE");
    client.Timeout = -1;
    var request = new RestRequest(Method.GET);
    IRestResponse response = client.Execute(request);
    Console.WriteLine(response.Content);
    package main
    import (
      "fmt"
      "net/http"
      "io/ioutil"
    )
    func main() {
      url := "https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE"
      method := "GET"
      client := &http.Client {
      }
      req, err := http.NewRequest(method, url, nil)
      if err != nil {
        fmt.Println(err)
      }
      res, err := client.Do(req)
      defer res.Body.Close()
      body, err := ioutil.ReadAll(res.Body)
      fmt.Println(string(body))
    }
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    Request request = new Request.Builder()
      .url("https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE")
      .method("GET", null)
      .build();
    Response response = client.newCall(request).execute();
    var settings = {
      "url": "https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE",
      "method": "GET",
      "timeout": 0,
    };
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    #import <Foundation/Foundation.h>
    dispatch_semaphore_t sema = dispatch_semaphore_create(0);
    NSMutableURLRequest *request =
            [NSMutableURLRequest requestWithURL:[NSURL URLWithString:
            @"https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE"]
      cachePolicy:NSURLRequestUseProtocolCachePolicy
      timeoutInterval:10.0];
    [request setHTTPMethod:@"GET"];
    NSURLSession *session = [NSURLSession sharedSession];
    NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
    completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
      if (error) {
        NSLog(@"%@", error);
      } else {
        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
        NSError *parseError = nil;
        NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
        NSLog(@"%@",responseDictionary);
        dispatch_semaphore_signal(sema);
      }
    }];
    [dataTask resume];
    dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
    import requests
    url = "https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE"
    payload = {}
    headers= {}
    response = requests.request("GET", url, headers=headers, data = payload)
    print(response.text)
    require "uri"
    require "net/http"
    url = URI("https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE")
    https = Net::HTTP.new(url.host, url.port);
    https.use_ssl = true
    request = Net::HTTP::Get.new(url)
    response = https.request(request)
    puts response.read_body
    import Foundation
    var semaphore = DispatchSemaphore (value: 0)
    var request = URLRequest(url: URL(string:"https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE")!,timeoutInterval: Double.infinity)
    request.httpMethod = "GET"
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
      semaphore.signal()
    }
    task.resume()
    semaphore.wait()
    /*!
     * GuGuData API Request Node.js Demo
     * 咕咕数据 API Node.js 请求 DEMO
     * 咕咕数据,专业的数据提供商,提供全面的数据接口 API,并提供专业全面的数据接口、商业数据分析。
     * 让数据成为您的生产原料。
     * https://www.gugudata.com
     */
    
    /* 咕咕数据 API 请求 DEMO ***开始***/
    // 导入相关类库
    var request = require("request");
    var querystring = require("querystring");
    var api_host = "https://api.gugudata.com";
    var api_path = "/location/geodecode"; // todo: 注意修改请求对应的 API 接口
    // todo: 注意修改构造请求参数
    var data = {
     appkey:'YOUR_APPKEY', longitude:'YOUR_VALUE', latitude:'YOUR_VALUE'
    };
    var content = querystring.stringify(data);
    var options = {
        method: "GET",
        url: api_host + api_path + "?" + content,
        headers: {}
    };
    // 发送网络请求
    var requestGuGuData = request(options, (error, response) => {
        if (error) throw new Error(error);
        console.log("********接口响应返回 JSON 数据********");
        console.log(JSON.parse(response.body));
        requestGuGuData.end();
        console.log("********接口响应结束********");
    });
    /* 咕咕数据 API 请求 DEMO ***结束***/
    <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.gugudata.com/location/geodecode?appkey=YOUR_APPKEY&longitude=YOUR_VALUE&latitude=YOUR_VALUE",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 0,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
  • 接口 SDK
    • 目前 SDK Alpha 版本部分商业用户内测中,建议开发者直接通过上面的请求 RESTful API 方式进行更加灵活、方便地调用。

  • 常见问题 Q&A
    • Q: 数据请求有缓存吗?

      A: 我们为所有数据请求提供实时响应。对于定期更新的数据,我们在其更新周期内实施缓存策略,以优化性能。

    • Q: 如何保证请求时 key 的安全性?

      A: 我们建议将对 API 的请求操作放置在您的应用程序后端。这样,前端请求只与您的后端服务交互,确保了更高的安全性和易于维护的架构。

    • Q: 接口可以用于哪些开发语言?

      A: 我们的接口支持所有能进行网络请求的开发语言,便于在各类项目中快速整合数据。

    • Q: 接口的性能可以保证吗?

      A: 我们的接口后台使用与商业级项目相同的架构,保证了稳定且高效的性能。您可以通过访问测试接口了解更多性能信息。

  • 服务协议

    用户应当充分阅读本协议,用户使用咕咕数据 API 服务亦视为接受本协议。

    一 定义

    咕咕数据 API 服务:由咕咕数据数据平台提供的数据 API 服务。

    用户:以任何形式使用咕咕数据的自然人、法人或其他组织。

    二 用户保证

    1. 用户同意并保证,在本协议有效期内,咕咕数据有权于任何时间要求用户提交相关资质证明资料原件及/或其他资料信息,用户对其所提交信息的真实完整、合法有效性承担保证责任。

    2. 用户同意并保证,合法并如约使用咕咕数据 API 服务。用户对其行为产生的任何法律责任自行独立承担,与咕咕数据无关。

    三 用户的权利与义务

    1. 用户有权就咕咕数据申请账号,用户注册账号,应向咕咕数据提供真实完整且合法有效的信息。如用户信息发生任何变更,用户应于变更后书面通知咕咕数据并提供最新资料信息。

    2. 用户需要自行保管其帐号和密码。用户帐号、密码使用权仅属于初始申请注册人,禁止赠与、借用、租用、转让或者售卖,如果用户进行此类操作导致密码泄露造成损失的,咕咕数据并不承担责任。

    3. 用户应按使用咕咕数据的实际发送数量,根据咕咕数据页面公布资费标准向咕咕数据支付相应的费用。

    4. 用户保证其所提供的手机号码列表的真实性、合法性、有效性及许可性,用户有义务对手机列表进行筛选。否则咕咕数据有权随时终止本协议。

    5. 用户在使用咕咕数据 API 服务期间,承诺并保证:

    (1) 遵守所有中华人民共和国法律法规和国际上有关互联网和短信的协议、规定、程序和惯例;

    (2) 不利用咕咕数据 API 服务进行干扰或扰乱咕咕数据网络服务或其他正常使用;

    (3) 不行使其他可能给咕咕数据带来任何不利影响的行为或者法律及政策禁止的行为。

    6. 用户不得利用咕咕数据 API 服务发送以下内容的短信:

    (1)接受方事先没有提出要求或者同意接受的广告等宣传性或营销性内容;

    (2)含有病毒、恶意代码、色情、反动等不良信息或有害信息;

    (3)地产、医疗、教育、留学、移民等相关内容;

    (4)冒充任何人或机构,或以虚伪不实的方式谎称或使人误认为与任何人或任何机构有关;

    (5)侵犯他人著作权或其他知识产权,或违反保密、雇佣或不披露协议披露他人商业秘密或保密信息。

    7. 用户应对相关数据自行存储和备份并至少保留六十日。根据咕咕数据或国家主管部门的要求,用户应向其提供备份内容。用户使用咕咕数据 API 服务,不得于任何时间任何事件中使用咕咕数据的 Logo、服务标记、域名及其他具有咕咕数据显著特征的标识。

    8. 用户应当按照本协议以及咕咕数据不时公布的规定,妥善使用咕咕数据 API 服务并为其行为负责。因用户行为导致咕咕数据遭受诉讼、索赔及/或处罚的,用户应赔偿咕咕数据因此造成的全部损失。

    9. 本协议一经生效咕咕数据即有权永久免费使用用户的商业名称、商标、Logo 等信息作为案例宣传咕咕数据旗下的相关服务。

    10. 用户同意接收来自咕咕数据的邮件及短信,包括但不限于商业推广信息等。

    四 咕咕数据的权利与义务

    1. 咕咕数据对用户行为无审核监督义务。因用户行为给咕咕数据造成的一切损失,咕咕数据有权向用户追偿。

    2. 咕咕数据对其提供给用户的服务质量做出如下承诺:

    (1)咕咕数据为客户发送的短信数量是真实可信的实际数量;

    (2)咕咕数据会向客户提供合理的建议和协助来帮助用户提高发送质量;

    (3)咕咕数据会提供必要的客户投诉与答疑服务。

    3. 咕咕数据有权随时调整咕咕数据 API 服务的资费,但该调整不会对用户已购买的服务产生影响。

    4. 咕咕数据有权对咕咕数据 API 服务进行定期或不定期的升级或完善,但应提前在相关页面进行公告。如用户因此受到影响,咕咕数据无需为此承担任何责任。

    5. 咕咕数据有权根据自己的判断对用户是否违反本协议约定及咕咕数据 API 服务使用规则做出认定。用户若有违反的,咕咕数据有权随时中止或终止本协议。咕咕数据无需就此征得用户同意或提前通知用户。

    6. 因非咕咕数据原因导致的本协议提前终止,用户已经支付而尚未使用的费用咕咕数据有权不予退还。

    7. 鉴于互联网服务的特殊性,对因不可抗力、第三方服务、黑客攻击、政策影响及其他任何非咕咕数据原因引起的服务中断、数据丢失等,咕咕数据均无需承担任何责任。

    五 知识产权

    1. 咕咕数据服务中包含的任何文字、图表、音频、视频和/或软件(包括但不限于软件中包含的图表、动画、音频、视频、界面实际、数据和程序、代码、文档)等信息或材料均受著作权法、商标法或其它法律法规的保护,未经相关权利人书面同意,用户不得以任何方式使用该等信息或材料,但出于使用咕咕数据服务目的而使用的除外。

    2. 除本协议明确允许的以外,用户不得以任何形式或任何方式对咕咕数据服务部分或全部内容进行修改、出租、租赁、出借、出售、分发、复制、创作衍生品或用于任何商业用途。

    3. 用户使用咕咕数据发布的信息不得侵犯任何第三人的知识产权,未经相关权利人之事先书面同意,用户不得以任何方式上传、发布、修改、传播或复制任何受著作权保护的材料、商标或属于其他人的专有信息。

    4. 若您认为您的知识产权或其他合法权益被侵犯,请向咕咕数据提供以下资料:

    (1) 对涉嫌侵权内容拥有知识产权或其他合法权益的权属证明;

    (2) 权利人具体的主体资质和联络信息,包括个人的姓名、身份证或护照复印件、单位的营业执照复印件或者其他资质证明复印件、通信地址及电话号码等;

    (3) 涉嫌侵权内容在本网站上的位置;

    (4) 对侵权情况的详细描述;

    (5) 在权利通知中加入如下关于通知内容真实性的声明:“由以上操作所引起的一切后果,与咕咕数据无关,由我本人/公司承担。” 在签字或加盖公章后发往以下邮箱: support@gugudata.com

    六 隐私权

    1. 保护用户的隐私是咕咕数据的一项基本政策。

    2. 适用于用户的隐私的相关条款请参见《隐私协议》

    七 免责声明

    1. 鉴于网络服务的特殊性,咕咕数据不保证网络服务的绝对及时性、安全性和准确性,用户同意咕咕数据有权不经事先通知,随时变更、中断或终止部分或全部的网络服务而无论同意与否,咕咕数据对用户和任何第三人均无需承担任何责任。

    2. 用户经由咕咕数据服务与广告商进行通讯联系或商业往来或参与促销活动,完全属于用户与广告商之间的行为,与咕咕数据没有任何关系,若因商业行为所产生之任何损害或损失,咕咕数据不承担任何责任。

    3. 用户明确同意其使用咕咕数据服务所存在的风险及其后果将完全由其自己承担,咕咕数据对用户不承担任何责任。如因用户违反有关法律、法规或本协议项下的任何条款而给咕咕数据或任何其他第三人造成损失,用户同意承担由此造成的损害赔偿责任。

    4. 咕咕数据提供的股票、基金、债券、外汇等行情数据以及其他资料均来自相关合作方,仅作为用户获取信息之目的,并不构成投资建议。用户理解并同意,咕咕数据提供的数据仅供参考,不保证数据的准确性、及时性或完整性。因依赖于此类数据而产生的任何投资决策和相应风险完全由用户自行承担。市场有风险,投资需谨慎。

    八 其他

    1. 本协议的版权归咕咕数据所有,咕咕数据保留对本协议的一切解释和修改权利。

    2. 本协议的订立、执行和争议的解决均应适用中华人民共和国法律。如双方就本协议内容或其执行发生任何争议,双方应尽量友好协商解决;协商不成时,任何一方均可向咕咕数据所在地有管辖权的人民法院提起诉讼。

    3. 咕咕数据行使本协议的任何权利或规定,不构成对前述权利之放弃。

    4. 如本协议中的任何条款完全或部分无效,本协议的其余条款仍有效并且有约束力。

  • 技术支持