Developer REST API v1

Google Maps CID & Place ID API

Automate Google Business Profile CID lookup, short link expansion (maps.app.goo.gl), Place ID conversions, and review link generation directly from your backend services.

Authentication & Headers

All API requests require an API Key passed either via the HTTP header X-API-Key or as a Bearer token in the Authorization header:

Header: X-API-Key: cid_live_your_api_key_here
# Or Bearer:
Authorization: Bearer cid_live_your_api_key_here

To obtain your API key, please select a plan from our Pricing page.

POST /api/resolve

Resolves any Google Maps share URL (maps.app.goo.gl, goo.gl/maps), desktop browser URL, or Google Place ID (ChIJ...) to its permanent decimal CID, Hex CID, and review links.

Request Payload (JSON)

{ "url": "https://maps.app.goo.gl/9ZpL9vW2Z5Xy8" }

Response Example (200 OK)

{ "title": "Osiris Bilişim", "cid": "11401689387182079980", "hex_cid": "0x9e3af016c2543fec", "place_id": "ChIJb7c_5aG3yhQR7D9UwhbvOp4", "rating": "5.0", "reviews_count": 48, "maps_url": "https://maps.google.com/?cid=11401689387182079980", "review_url": "https://search.google.com/local/writereview?placeid=ChIJb7c_5aG3yhQR7D9UwhbvOp4", "schema_hasmap": "https://maps.google.com/?cid=11401689387182079980", "rate_limit": { "authenticated": true, "limit": "unlimited", "remaining": 999999 } }

Code Example (Python)

import requests url = "https://mapscidfinder.com/api/resolve" headers = { "Content-Type": "application/json", "X-API-Key": "cid_live_your_key_here" } payload = { "url": "https://maps.app.goo.gl/9ZpL9vW2Z5Xy8" } response = requests.post(url, json=payload, headers=headers) data = response.json() print("CID Number:", data.get("cid")) print("Review Link:", data.get("review_url"))

POST /api/search

Searches Google Maps businesses by brand/company name and country code, returning an array of candidate listings with verified CIDs.

Request Payload (JSON)

{ "name": "Kadıköy Diş Kliniği", "country": "TR" }

Response Example (200 OK)

{ "results": [ { "title": "Kadıköy Özel Diş Kliniği", "address": "Caferağa Mah. Moda Cad. No:12 Kadıköy / İstanbul", "cid": "14838291049281729103", "hex_cid": "0xce129482fa81044f", "place_id": "ChIJX81294a20hQR78921829381", "rating": "4.9", "reviews_count": 124, "maps_url": "https://maps.google.com/?cid=14838291049281729103" } ] }

POST /api/convert

Bidirectional converter between decimal CID numbers and 64-bit Hexadecimal notation (supports both 0x... prefix and raw hex strings).

Request Payload (JSON)

{ "cid": "0x9e3af016c2543fec" }

Response Example (200 OK)

{ "cid_decimal": "11401689387182079980", "hex_cid": "0x9e3af016c2543fec", "maps_url": "https://maps.google.com/?cid=11401689387182079980", "schema_hasmap": "https://maps.google.com/?cid=11401689387182079980" }

HTTP Status Codes

Status Code	Description	Action
`200 OK`	Request succeeded and result payload returned.	Parse response body.
`400 Bad Request`	Missing URL, Place ID, or malformed JSON body.	Verify your request payload structure.
`401 Unauthorized`	Invalid API Key or expired credentials.	Verify your `X-API-Key` in Pricing.
`429 Too Many Requests`	Free daily IP quota (5 queries) or monthly plan quota reached.	Upgrade plan or check `X-RateLimit-Reset`.
`500 Server Error`	Target Google Maps profile unreachable or temporary proxy block.	Retry request with exponential backoff.

Geliştirici REST API v1

Google Maps CID & Place ID API Dokümantasyonu

Google İşletme Profili CID çözümleme, kısa link açma (maps.app.goo.gl), Place ID dönüştürme ve doğrudan 5 yıldızlı yorum linki üretimini kendi backend servislerinize ve yazılımlarınıza bağlayın.

Kimlik Doğrulama & Başlıklar

Tüm API istekleri X-API-Key başlığı veya Authorization başlığında Bearer belirteci olarak geçerli bir anahtar gerektirir:

Header: X-API-Key: cid_live_api_anahtariniz
# Veya Bearer:
Authorization: Bearer cid_live_api_anahtariniz

API anahtarınızı almak için lütfen Fiyatlandırma sayfamızdan bir paket seçin.

POST /api/resolve

Tüm Google Haritalar paylaşım linklerini (maps.app.goo.gl, goo.gl/maps), masaüstü bağlantılarını veya Place ID (ChIJ...) kodlarını kalıcı onluk CID, Hex CID ve 5 yıldızlı yorum linkine dönüştürür.

İstek Gövdesi (JSON Payload)

{ "url": "https://maps.app.goo.gl/9ZpL9vW2Z5Xy8" }

Yanıt Örneği (200 OK)

Kod Örneği (Python)

import requests url = "https://mapscidfinder.com/api/resolve" headers = { "Content-Type": "application/json", "X-API-Key": "cid_live_api_anahtariniz" } payload = { "url": "https://maps.app.goo.gl/9ZpL9vW2Z5Xy8" } response = requests.post(url, json=payload, headers=headers) data = response.json() print("CID Numarası:", data.get("cid")) print("Yorum Linki:", data.get("review_url"))

POST /api/search

Google Haritalar'da işletme/marka adı ve ülke koduna göre arama yaparak doğrulanmış CID numaralarıyla birlikte eşleşen işletmeleri döner.

İstek Gövdesi (JSON Payload)

{ "name": "Kadıköy Diş Kliniği", "country": "TR" }

Yanıt Örneği (200 OK)

POST /api/convert

64-bit onluk (decimal) CID sayısı ile Google'ın dahili sistemlerinde kullandığı onaltılık (hexadecimal) kod arasında iki yönlü dönüştürme yapar (0x... öneki desteklenir).

İstek Gövdesi (JSON Payload)

{ "cid": "0x9e3af016c2543fec" }

Yanıt Örneği (200 OK)

HTTP Durum Kodları (Status Codes)

Durum Kodu	Açıklama	Yapılması Gereken
`200 OK`	İstek başarıyla tamamlandı ve veri döndü.	Yanıt gövdesini (JSON) işleyin.
`400 Bad Request`	URL, Place ID eksik veya geçersiz JSON yapısı.	İstek gövdesi (payload) formatını kontrol edin.
`401 Unauthorized`	Geçersiz veya süresi dolmuş API Anahtarı.	Fiyatlandırma sayfasından anahtarınızı kontrol edin.
`429 Too Many Requests`	Günlük ücretsiz IP kotası (5 istek) veya paket kotası doldu.	Paketinizi yükseltin veya `X-RateLimit-Reset` bekleyin.
`500 Server Error`	Google Harita profiline erişilemedi veya geçici sunucu hatası.	İsteği üstel geri çekilme (exponential backoff) ile yeniden deneyin.