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.