100 크레딧 무료, 카드 등록 없이지금 시작하기
Logo
Apple Maps logoApple Maps API

Apple Maps 장소와 평점 데이터 API

SocialCrawl API 키로 지도 영역의 Apple Maps 장소를 검색하고 id로 장소를 조회해, 평점, 영업시간, 연락처, 편의 시설을 구조화 JSON으로 가져옵니다. 호출은 크레딧으로 과금됩니다.

Apple Maps logo
/v1/apple_maps

활성 엔드포인트는 2개입니다. 장소 검색과 장소 상세 조회를 지원합니다.

  • GET /v1/apple_maps/search
  • GET /v1/apple_maps/places

Apple Maps 엔드포인트

공개 Apple Maps 데이터를 읽는 엔드포인트는 2개입니다. 지도 영역의 장소 검색과, Apple Maps id로 최대 50곳을 한 번에 읽는 장소 상세 조회를 지원합니다.

장소 검색

1 크레딧
/v1/apple_maps/search

지도 상자(bbox, 서쪽,북쪽,동쪽,남쪽 순서의 십진 도) 또는 한 지점(lat과 lng) 주변에서 검색어에 맞는 장소를 호출당 약 20곳 반환합니다. 장소마다 Apple Maps id, 이름, Apple Maps 링크, 카테고리, 주소, 도시, 국가, 전화번호, 좌표, 사진, 가격대, 요일별 영업시간, 현재 영업 여부, 웹사이트가 포함됩니다. 검색의 평점은 Yelp 5점 만점이며 리뷰 수, 리뷰 발췌 최대 3개, yelp 엔드포인트와 연결하는 Yelp id가 함께 반환됩니다. strict_bbox는 기본 true이고 false면 상자 바로 바깥의 장소도 포함합니다. 한 번의 호출은 상자 하나를 다루므로 도시 전체는 더 작은 상자로 나누어 조회합니다. 한 지점은 상자보다 훨씬 좁은 영역만 다룹니다. 표준 티어(1 크레딧)입니다.

query, bbox or lat and lng, strict_bbox

/v1/apple_maps/places

Apple Maps id 1개에서 50개까지 한 번의 호출로 보낸 순서대로 반환하며 language(예: fr-FR)를 선택할 수 있습니다. 설명, 카테고리 목록, 도시와 지역과 우편번호로 나뉜 주소, 사업자의 등록 인증 여부, 편의 시설, 메뉴 링크, 주문 링크가 추가됩니다. Apple 평점은 0에서 100점이며 음식과 음료, 분위기, 고객 서비스 세부 평점이 있고, Apple 평점이 없는 장소는 Yelp 5점 만점 평점을 가집니다. place.ext.rating_source가 평점을 매긴 곳을 알려 줍니다. 알 수 없는 id는 결과에서 빠지고 data._warnings에 표시되며 나머지 장소는 그대로 반환됩니다. 아는 id가 하나도 없으면 빈 결과이고 무료입니다. 표준 티어(1 크레딧)입니다.

ids, language

Apple Maps API2개 엔드포인트 지원
문서 보기
Places

Apple 지도 장소를 ID로 한 번에 최대 50곳까지 돌려줍니다. 장소마다 평점과 평점 출처, 주소, 전화번호, 영업시간, 편의시설, 사진, 웹사이트, 메뉴가 담깁니다.

이미 찾은 장소 정보를 새로 받거나, 평점과 영업시간을 비교하거나, Apple 지도 ID 목록을 한꺼번에 보강할 때 사용하세요.

1크레딧

GET/v1/apple_maps/places?ids=5144915183449522016%2C4568414994170597789

ids · One to 50 Apple Maps place ids, comma-separated, for example 5144915183449522016. GET /v1/apple_maps/search returns them in place.id.

$ curl https://www.socialcrawl.dev/v1/apple_maps/places?ids=5144915183449522016%2C4568414994170597789 \
    -H "x-api-key: sc_YOUR_API_KEY"
대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다

Apple Maps API 동작

Apple Maps도 다른 SocialCrawl 데이터 엔드포인트와 같습니다. API 키로 GET /v1/apple_maps/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다.

호출 인증

x-api-key 헤더에 키를 보냅니다. 공개 읽기에 Apple 계정이나 개발자 토큰은 필요 없습니다. SocialCrawl 전 플랫폼에 같은 키를 사용합니다.

GET과 쿼리 파라미터

검색은 query(최대 500자)와 함께 bbox 또는 lat과 lng 쌍을 받습니다. 장소 상세는 쉼표로 구분한 Apple Maps id 1개에서 50개를 ids로 받습니다. 과금 전에 형식을 검증합니다.

크레딧 과금

Apple Maps의 모든 경로는 1 크레딧이며 id 50개를 보내도 한 번의 호출입니다. 캐시 히트는 0입니다.

JSON 봉투

응답 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. 목록 응답은 items와 total을 가집니다.

연동 순서

대부분 제품은 영역의 장소를 먼저 찾은 뒤 필요한 장소만 일괄로 읽습니다.

01지도 상자 검색
GET /v1/apple_maps/search?query=…&bbox=…

Yelp 평점과 리뷰 발췌가 있는 약 20곳의 PlaceList

한 번의 호출은 상자 하나를 다룹니다. 도시 전체는 더 작은 상자로 나누어 조회합니다.

02장소 일괄 조회
GET /v1/apple_maps/places?ids=…

Apple 평점, 영업시간, 편의 시설이 있는 최대 50곳의 PlaceList

place.id는 검색 결과 행에서 가져옵니다. 장소는 보낸 순서대로 반환됩니다.

03Yelp 리뷰 읽기
GET /v1/yelp/business/reviews?id=…

yelp 엔드포인트의 리뷰

검색 결과 행의 place.ext.yelp_id는 GET /v1/yelp/business/reviews가 받는 id입니다.

요청
GET /v1/apple_maps/search?query=coffee&bbox=-74.000,40.765,-73.970,40.745
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here

GET /v1/apple_maps/places?ids=5144915183449522016,4568414994170597789
응답 봉투
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "5144915183449522016",
        "name": "Culture Espresso",
        "category": "Espresso Bar",
        "address": "72 W 38th St, New York, NY 10018",
        "rating": { "value": 93, "max": 100 },
        "reviews_count": 98,
        "ext": {
          "rating_source": "Apple",
          "category_ratings": { "Food & Drink": 97 },
          "weekly_hours": { "monday": ["07:00 - 19:00"] }
        }
      }
    ],
    "total": 1
  },
  "credits_used": 1,
  "credits_remaining": 9999,
  "request_id": "req_…",
  "cached": false
}

data 형태

아키타입이 맞는 범위에서 필드 이름은 SocialCrawl 나머지와 같습니다. 한 번 파싱해 여러 플랫폼에 재사용합니다.

PlaceList (검색)search

items[]에 id, 이름, url, 카테고리, 척도가 있는 평점, reviews_count, 주소, 도시, 국가, 전화번호, 좌표, 사진, 가격대, ext.rating_source, ext.review_snippets, ext.yelp_id, ext.weekly_hours

PlaceList (장소 상세)places

items[]를 보낸 순서대로 반환하며 설명, 카테고리 목록, 지역, 우편번호, verified, ext.amenities, ext.menu_url, ext.order_url 포함, 알 수 없는 id는 _warnings에 표시

평점과 척도places

rating.value와 rating.max(Apple 100, Yelp 5), ext.rating_source, 음식과 음료, 분위기, 고객 서비스의 ext.category_ratings

Yelp 연결search

검색 결과 행마다 ext.yelp_id와 ext.review_snippets 최대 3개를 담아 yelp 엔드포인트에 바로 연결

게이트웨이 내부

다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. Apple Maps는 사이드카가 아닙니다.

  1. 01

    엣지가 호출을 받음

    Next.js catch-all이 Hono 소셜 API로 라우팅합니다. request_id를 만들고 키를 인증한 뒤 분당 600회, 키당 동시 50개 한도를 적용합니다.

  2. 02

    검증 후 차감

    레지스트리에서 apple_maps 경로를 찾습니다. 필수 파라미터와 형식 검사를 먼저 합니다. 잘못된 입력은 과금 없이 400입니다. 유효 호출은 읽기를 시작하기 전에 티어 비용을 원자적으로 차감합니다.

  3. 03

    캐시 또는 수집

    platform + resource + params로 캐시 키를 만듭니다. 히트면 credits_used = 0으로 즉시 반환합니다. 미스면 공개 데이터를 실시간으로 읽으며 5xx나 네트워크 오류는 재시도하고 소스가 불안정하면 서킷 브레이커를 사용합니다.

  4. 04

    정규화 후 반환

    Apple Maps 데이터를 PlaceList 아키타입으로 매핑하고 평점 출처, 영업시간, 편의 시설, Yelp id를 place.ext에 담아 검증한 뒤 성공 봉투로 감싸 과금 감사 로그를 남깁니다.

운영에서 중요한 과금 규칙

  • search, places: 1 크레딧
  • places: id 50개까지 1 크레딧
  • 캐시 히트: 0 크레딧
  • 빈 응답 / 하드 실패: 자동 환불
  • 아는 id가 하나도 없는 places 조회: 빈 결과, 무료
  • 잘못된 파라미터: 400, 과금 없음
  • 크레딧 부족: 402, 과금 없음
  • 알 수 없는 id는 결과에서 빠지고 data._warnings에 표시
  • 검색은 호출당 약 20곳, 호출당 상자 하나

Apple Maps 데이터 수집 방식

Apple Maps는 공개 읽기 데이터입니다. SocialCrawl 스키마로 정규화하므로 별도 벤더 SDK를 배울 필요가 없습니다.

이 API에서 Apple Maps의 의미

공개 Apple Maps 장소 정보입니다. 사업장 정보, 영업시간, Apple 평점, 편의 시설과 함께 Apple Maps 검색이 보여 주는 Yelp 평점과 리뷰 발췌를 담습니다.

SocialCrawl 수집 경로

공개 데이터를 요청 시점에 읽어 서버에서 정규화합니다. Apple 개발자 계정이나 Yelp 연동을 직접 운영할 필요가 없습니다.

엣지에서 나가는 형태

두 경로 모두 PlaceList입니다. 평점을 매긴 곳은 place.ext.rating_source에 표시되고 모든 평점은 각자의 척도를 유지하므로 100점 만점의 93점이 5점 만점의 4.65점으로 바뀌지 않습니다.

라이브로 제공하지 않는 것

리뷰 작성자 이름, 길찾기와 경로 안내, 사업자용 도구는 제공하지 않습니다.

필드 매핑
Apple Maps place→ place.*Apple Maps id, 이름, 링크, 카테고리, 주소, 전화번호, 좌표, 웹사이트
rating, review count and snippets→ place.ext.rating_source / review_snippets / yelp_id평점 출처, 리뷰 수, 발췌, yelp 엔드포인트와 연결하는 Yelp id
hours and amenities→ place.ext.weekly_hours / amenities요일별 영업시간과 편의 시설 목록

이 API의 활용 분야

이 API가 가장 많이 사용되는 작업입니다.

2active Apple Maps endpoints in the registry
1Apple Maps 전 경로의 호출당 크레딧

지역 사업장 목록, 등록 정보 점검, 리뷰 연결

호출은 지도 상자 검색에서 시작해 필요한 장소를 일괄로 읽는 방식으로 이어집니다. Apple 평점을 0에서 100점 척도 그대로 Yelp 5점 만점 평점과 함께 제공하고, 한 번의 호출로 50곳을 1 크레딧에 읽으며, 검색 결과 행마다 yelp 엔드포인트와 연결하는 Yelp id를 담습니다.

라이브 미스는 요청 시점에 공개 데이터를 읽습니다. 반복 호출은 캐시에서 0 크레딧으로 응답합니다.

활용 사례

이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.

지역 사업장 목록

Python, 예약 작업

더 작은 상자로 나누어 search로 도시 전체를 훑은 뒤 places를 한 번에 id 50개까지 호출해 전화번호, 웹사이트, 영업시간을 채웁니다.

등록 정보 정확도 점검

Node, 웨어하우스 적재

관리하는 id마다 places를 호출해 영업시간, 전화번호, 주소를 Apple Maps 표시와 비교하고 등록 인증 여부를 확인합니다.

리뷰 데이터 보강

Python, notebooks

상자 안의 카테고리를 search로 찾은 뒤 place.ext.yelp_id를 yelp 리뷰 엔드포인트에 넘겨 리뷰 전문을 가져옵니다.

Apple Maps API 호출 방법

Apple Maps의 모든 경로는 1 크레딧입니다. 캐시 히트는 무료입니다.

curl "https://www.socialcrawl.dev/v1/apple_maps/search?query=coffee&bbox=-74.000,40.765,-73.970,40.745" \n  -H "x-api-key: sc_your_api_key_here"
curl "https://www.socialcrawl.dev/v1/apple_maps/places?ids=5144915183449522016,4568414994170597789" \n  -H "x-api-key: sc_your_api_key_here"
Apple Maps logoSocialCrawl의 Apple Maps

카탈로그 전 구간과 같은 키

엔드포인트

Apple Maps API는 어떤 데이터를 돌려주나요

모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.

자주 묻는 질문

자주 묻는 질문

API, 요금제, 기능에 대한 질문과 답변입니다.

문의하기
SocialCrawl 애플 지도 API는 무엇을 제공하나요?
엔드포인트 2종(Places and Search)으로 지도 범위 안의 장소 검색과 애플 지도 ID로 장소 상세 조회를 받아요. 다른 94개 플랫폼과 같은 통합 JSON으로 와요.
애플 개발자 계정이나 MapKit 토큰이 필요한가요?
아니요. SocialCrawl API 키 하나로 호출하니 애플 개발자 계정이나 MapKit 토큰, 애플 키를 따로 관리하지 않아도 돼요.
애플 지도 평점과 리뷰도 받을 수 있나요?
네, 검색 결과에는 장소마다 Yelp 평점(5점 만점), 리뷰 수, 리뷰 문구가 최대 세 개까지 와요. 장소 상세에는 평점의 만점 기준과 평가한 곳이 함께 오고, 애플 자체 100점 만점 점수와 음식, 분위기, 고객 서비스 세부 평점도 들어 있어요.
애플 지도 장소 ID는 어디서 찾나요?
GET /v1/apple_maps/search를 호출하면 장소마다 place.id에 애플 지도 ID가 담겨 와요. 이 ID를 GET /v1/apple_maps/places에 넣으면 전체 정보를 읽을 수 있어요.
애플 지도 API는 크레딧이 얼마나 드나요?
애플 지도의 모든 경로가 호출당 1 크레딧이고 캐시 히트는 무료예요. 새 계정은 카드 없이 무료 100 크레딧을 받아요.
Apple Maps 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Apple Maps 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Apple Maps 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
Apple Maps 스크래핑 API와 공식 Apple Maps API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Apple Maps 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.

AI에게 SocialCrawl을 물어보세요

Apple Maps API 레퍼런스 문서 보기

🤖 AI 에이전트나 LLM이신가요? 이 페이지를 markdown으로 읽어보세요